Users, Roles, and Permissions

xorlab Security Platform defines the concepts of Roles, Permissions and Scopes:

A Permission denotes an atomic action (in terms of access control) bound to a specific Scope.
A Scope limits a permission to a specific context. For example, a user’s current tenant Scope may constrain a Permission to not extend beyond their own tenant.
A Role is a set of Scopes with Permissions. If needed, Roles can be arbitrarily composed and assigned to users.

Roles can be assigned to users but permissions cannot be directly assigned to users. Each subsystem of xorlab Security Platform could define its own set of permissions, although currently only the XCC (Control Center) defines such permissions by default. xorlab Security Platform is shipped with a set of predefined roles. However, the configuration allows for the creation of additional roles with arbitrary permission mappings.

Assigning Roles to Users

Role assignment is managed by the authorization system, which is part of the authentication process. Typically, this occurs outside the xorlab Security Platform (XSP) in an Identity Provider (IdP), an LDAP directory, etc. However, XSP supports configuring role mappings. This allows roles defined within an organization to be mapped to XSP roles, whether predefined or custom. To configure role mapping, you need to edit the auth.yml file for each authentication backend. Each backend that supports role mapping uses the roleMapping configuration parameter. Please refer to the Authentication page for additional information.

usernamePasswordAuthBackends:
  # Name of the authentication backend, has to be unique among all authentication backends.
  <authentication backend name>:
    # ...

    ldapAuthDataSources:
      <LDAP data source name>:
        # ...

        authorization:
          # Query for roles using a nested search within a subtree of a directory.
          query:
            # ...

            # The role name to be used as input for the roleMapping.
            # If this is not set, the DN of the role entry is used.
            groupRoleAttribute: dn
        # ...

        # Maps a backend specific role to an ldap roleName. If a mapping is not defined an implicit identity-mapping is assumed.
        # Multiple backend roles can be mapped to the same ldap role.
        # E.g. {"xcc_login" -> "company1-group1", "xcc_admin" -> "company1-group1" }
        roleMapping:
          xcc_analyst: ["<organization role 1>", "<organization role 2>"]
          <custom role>: ["<another organization role>"]

saml2AuthBackends:
  # Name of the authentication backend, has to be unique among all authentication backends.
  <authentication backend name>:
    # ...

    # Mapping of xorlab Security Platform role mappings to SAML2 Assertion roles.
    roleMapping:
      xcc_analyst: ["<organization role 1>", "<organization role 2>"]
      <custom role>: ["<another organization role>"]

Predefined Roles and Permissions

Roles

The xorlab Security Platform defines a set of permissions that can be mapped to roles. XSP comes with a default set of roles, each of which is mapped to a predefined set of permissions. Administrators can create new roles and define their associated permissions. However, the permissions of predefined roles cannot be changed.

xorlab Security Platform role	Technical role identifier	Capabilities
User	`xcc_analyst`	- Release emails from quarantine - Reanalyze/Unlock emails - Send feedback for reported incidents - Submit misclassification reports - Create, delete, or modify search queries and campaigns - Update custom tags for messages, reported incidents, and uploaded files - Upload a file for analysis
User (Tenant-Restricted)	`xcc_tenant_analyst`	This user can only access resources on their own tenant and can: - Release emails from quarantine - Reanalyze/Unlock emails - Send feedback for reported incidents - Submit misclassification reports - View campaigns and saved searches (no modifications) - Update custom tags for messages, reported incidents, and uploaded files - Upload a file for analysis
Auditing User	`xcc_analyst_audit`	- View messages, reported cases, and analyzed files - View campaigns and saved searches - View the custom tags of messages - View items from black- and whitelists in the UI - View configuration lists in Expert Editor
Auditing User (Tenant-Restricted)	`xcc_tenant_analyst_audit`	This user can only access resources on their own tenant and can: - View messages, reported cases, and analyzed files - View campaigns and saved searches - View the custom tags of messages - View items from black- and whitelists in the UI - View configuration lists in Expert Editor
Admin	`xcc_admin`	- Isolate messages from user mailboxes - Modify black- and whitelists in the UI - Edit configuration lists in Expert Editor - Start a new backup and check the status of the running process - Edit system configurations - Other power user capabilities
Auditing Admin	`xcc_admin_audit`	- Everything that an `Auditing User` can view - View system configurations and backup status
Self-Serviced Quarantine User	`xcc_quarantine_user`	- Authenticate and log in via the UI - Change basic settings such as white/black theme - View emails in the `Malware`, `Extortion`, `Policy` and `Impersonation` quarantine - View and release emails from the `Phishing` and `Spam` quarantine.
Insights User	`xcc_insights`	Access to the statistics dashboards in the Insights section
Monitoring User	`xcc_monitor`	Access to `/monitoring` (Grafana)

Specification of a Custom Role

To specify a custom role, add it to roleToPermissionMappings in xcc.yml. You can find the list of available permissions in the Permissions-Role Matrix. A custom role consists of so called grant definition. Hint: You can query your current permissions as described here.

Grant Definition Syntax

<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

Notice: Omitting the <scopeDefinition> implies a global scope (full, unrestricted access) for a specific permission.

Example Grant Definitions

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.

Example Role Mapping

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

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_quarantine_user	xcc_insights	xcc_monitor
`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_asset_fetch` Allows retrieving analysis artifacts of messages, reported emails, and uploaded files	global	global	global	global	tenant:primary	tenant:primary	recipient:all\|quarantine:Airlock\|tenant:primary recipient:all\|quarantine:BEC\|tenant:primary recipient:all\|quarantine:Extortion\|tenant:primary recipient:all\|quarantine:Filter\|tenant:primary recipient:all\|quarantine:Impersonation\|tenant:primary recipient:all\|quarantine:Malware\|tenant:primary recipient:all\|quarantine:Phishing\|tenant:primary recipient:all\|quarantine:Spam\|tenant:primary
`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_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_quarantine_release` Allows the release of one or more quarantined messages	global		global		tenant:primary		recipient:all\|quarantine:BEC\|tenant:primary recipient:all\|quarantine:Phishing\|tenant:primary recipient:all\|quarantine:Spam\|tenant:primary
`xcc_quarantine_release_request_create` Allows creating a release request for one or more quarantined messages	global		global		tenant:primary
`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:Airlock\|tenant:primary recipient:all\|quarantine:BEC\|tenant:primary recipient:all\|quarantine:Extortion\|tenant:primary recipient:all\|quarantine:Filter\|tenant:primary recipient:all\|quarantine:Impersonation\|tenant:primary recipient:all\|quarantine:Malware\|tenant:primary recipient:all\|quarantine:Phishing\|tenant:primary recipient:all\|quarantine:Spam\|tenant:primary
`xcc_result_detail_fetch` Allows view of the email details	global	global	global	global	tenant:primary	tenant:primary	recipient:all\|quarantine:Airlock\|tenant:primary recipient:all\|quarantine:BEC\|tenant:primary recipient:all\|quarantine:Extortion\|tenant:primary recipient:all\|quarantine:Filter\|tenant:primary recipient:all\|quarantine:Impersonation\|tenant:primary recipient:all\|quarantine:Malware\|tenant:primary recipient:all\|quarantine:Phishing\|tenant:primary recipient:all\|quarantine:Spam\|tenant:primary
`xcc_result_detail_preview` Allows viewing of email previews (if available)	global	global	global	global	tenant:primary	tenant:primary	recipient:all\|quarantine:Airlock\|tenant:primary recipient:all\|quarantine:BEC\|tenant:primary recipient:all\|quarantine:Extortion\|tenant:primary recipient:all\|quarantine:Filter\|tenant:primary recipient:all\|quarantine:Impersonation\|tenant:primary recipient:all\|quarantine:Malware\|tenant:primary recipient:all\|quarantine:Phishing\|tenant:primary recipient:all\|quarantine:Spam\|tenant:primary
`xcc_result_detail_unlock` Allows unlocking of emails with encrypted attachments (Attachment Airlock)	global		global		tenant:primary		recipient:all\|quarantine:Airlock\|tenant:primary
`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:Airlock\|tenant:primary recipient:all\|quarantine:BEC\|tenant:primary recipient:all\|quarantine:Extortion\|tenant:primary recipient:all\|quarantine:Filter\|tenant:primary recipient:all\|quarantine:Impersonation\|tenant:primary recipient:all\|quarantine:Malware\|tenant:primary recipient:all\|quarantine:Phishing\|tenant:primary recipient:all\|quarantine:Spam\|tenant:primary
`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

​Assigning Roles to Users

​Predefined Roles and Permissions

​Roles

​Specification of a Custom Role

​Grant Definition Syntax

​Example Grant Definitions

​Permissions-Role Matrix