Data Access Control

SpectX allows to customise access rights both to files in SpectX Files in the Resource Tree (query scripts, datastore definition files, etc) and also to the data within the datastores. As well, different access modes can be configured for each of the data access protocols.

Files in the Resource Tree

SpectX Administrators can control user and group access to files in the SpectX resource tree by means of an access control list (ACL) which defines user, group and script access permissions to folders. These permissions are then passed down to the files within the folder. To view the access permissions list of a folder:

  1. Right-click on a file or folder in the resource tree.
  2. Select properties.

The list contains records, defining permitted operations for the actors (users, groups or resource tree paths):

{'user' | 'group' | 'execPath'} ':' name ':' permissions

where:

  • user defines a username of the end-user.

  • group defines a name of either a local group or one’s provisioned externally (via Integrated Windows Authentication or SAML SSO authentication schemes). Name $admin refers to all users with Administrator role.

  • execPath defines a prefix (a beginning) of a path to scripts in the resource tree, which can access the specified resources according to defined permissions.

    Note

    It is possible to use wildcard * as a value for the name to give it an “all” meaning.

  • permissions defines a set of allowed actions:

    Permission Int value Description
    l 1 (0x01)
    List - allows access to metadata of directory contained files:
    filename, size, last_modified.
    Enables displaying directory contained files in the resource tree.
    x 2 (0x02) Execute - allows execution of the files in a directory
    r 4 (0x04) Read - allows reading the content of files in a directory
    w 8 (0x08) Write - allows modification of the files in a directory
    c 16 (0x10) Create - allows creation of new files in a directory
    d 32 (0x20) Delete - allows removal of files in a directory

Note

  • ACL is defined only on folders - all files within will inherit the permissions from its parent folder.
  • Defined permissions of an ACL apply also to the folder itself (i.e not inherited from its own parent).
  • All values in ACL are case-sensitive.
  • Execution prevention may be circumvented when the read is allowed - content can be copied, pasted and saved to a location where execution is allowed.
  • Permissions can be withdrawn at any time by deleting the definition from the ACL.
  • The Administrator role can change permissions. Always and everywhere.
  • The user role can not change permissions. (Well, it can in the user’s own space, but that does not make much sense).

Examples

Consider the following example: the Access Control List for the /users/admin/datastores directory owned by the admin user. The admin has full permissions to this folder. Others have no permission.

Another example: give user john all permissions, group team-one permissions to list, read, and execute, and all the rest of users permission to list:

user:john:lrwxcd
group:team-one:lrx
user:*:l

Permissions in the ACL are cumulative - i.e when the actor matches multiple records in the ACL then all permissions defined in these records become effective. For example, if we add one more user to the ACL in the previous example:

user:john:lrwxcd
group:team-one:lrx
user:*:l
user:jane:rwx

then jane will have the list, read, write and execute permissions.

The execPath deserves perhaps a more detailed explanation. This allows to lock down a folder completely from accessing its content by users (either directly in resource tree or via Data Browser using sx:// protocol).

Consider the following example. Default permissions of /System/datastores allow listing and execution to all users. Although they can’t see the credentials of the datastores (since they don’t have read permission) they have access to all data. Suppose you need to provide a limited view (for instance excluding some sensitive data) to a group of users. We create a folder /shared/sensitive to keep the scripts implementing the view. We give the list and execute permissions to our target group:

group:$admin:lrwxcd           //Administrators should have full access for management
group:sensitive:lx            //members of sensitive group can list and execute scripts in /shared/sensitive folder

We also create a folder in /shared/datastores/sensitivedata and lock it down:

group:$admin:lrwxcd           //Administrators should have full access for management
user:*:0                      //no direct access to any user
execPath:/shared/sensitive:x  //allow execution from scripts from /shared/sensitive folder

These permissions allow only the scripts in the /shared/sensitive folder to execute datastores in /shared/datastores/sensitivedata. The users can not access datastores directly. Also, they can not change or see how sensitive data is manipulated in the scripts in /shared/sensitive. Hence these permissions guarantee that the target group can access only allowed data.

When scripts executing in such locked down folders create and/or update files in the same place (for instance by saving results), or include code from other scripts they also respective permissions by execPath. For instance, if the script handling sensitive data from the previous example needs to include some code from another script module in the same /shared/sensitive folder then we need to give read permission to scripts executing within shared/sensitive folder too:

group:$admin:lrwxcd           //Administrators should have full access for management
group:sensitive:lx            //members of sensitive group can list and execute scripts in /shared/sensitive folder
execPath:/shared/sensitive:r  //scripts executing within /shared/sensitive can read from files within it

Data in the Datastores

By default, the data within a datastore is accessible to all SpectX users.

However, access permissions to data located at different paths within the datastores can be customized using the read access control list (rACL). The rACL of a datastore is accessed by double-clicking on it, the rACL is then displayed in a new dialogue box. Here Spectx Administrators can set access privileges.

The rACL declares the subjects allowed to read the target specified files:

  • subject - individual users, groups or paths to executable scripts in the resource tree.
  • target - either prefix or GLOB expression specifying the path to the files within a datastore.

Both subject and target consist of their type and value:

subject_type : subject_value : target_type : target_value

where:

subject_type specifies the type of subject_value:

  • user declares subject_value to contain the username of an end-user.

  • group declares subject_value to contain group name defined locally or provided by external identity management system. $admin refers to all users with the Administrator role.

  • execPath declares subject_value to contain a path to executable script(s) in the resource tree, allowed to access the target data.

    Note

    You can use wildcard * in the subject_value to give it an “all” meaning.

target_type specifies the type of target_value:

  • prefix declares target_value to contain the prefix of the uri path (see section 3.3 of RFC3986).
  • glob declares target_value to contain glob pattern of the uri path. NB! Note that the pattern must specify the file part. Leaving this out will result in access being denied.

Note

  • All values in rACL are case-sensitive.
  • The API calls support only locally defined groups in specifying permissions. (This is because API does not support delegated authorization schemes like IWA or SAML)

rACL JSON structure

The rACL definitions are stored in the file system within the datastore definition file (*.sxds).

JSON structure is of the following format (as a member of "acl": {} map in datastore object):

"entries": [
    {
      "type": "<subject_type>",
      "value": "<subject_value>",
      "aclEntryType": "<target_type>",
      "aclEntryValue": "<target_value>",
      "permission": {
        "value": 4
      }
    },
]

The values are the same as described above.

<permission> is a map defining access control permission value for the rule. At the moment only "value" : 4 is supported.

Examples

Example: an rACL allowing all users to access files below root directory:

rACL

Consider another example. You are an infosec manager of an e-commerce shop. Your company develops the software in house and the developers need access to logs of the development environment but not to production ones, and testers need to read logs of both development and test environments and not production ones. Unfortunately the logs from all three environments are collected to the same Amazon S3 bucket. In this situation, you can define the following rACL to the datastore:

# administrators have access to all data
group:$admin:prefix:/
# developers have access only to logs of dev environment, contained in /logs/dev/ directory
group:developers:prefix:/logs/dev/
# testers have access to logs of both dev and test environments in /logs/dev/ and /logs/test/ directories,
# with max possible directory structure depth of 4 (e.g. /application/year/month/day/*)
group:testers:glob:/logs/@(dev|test)/****/*

Note that glob matches files differently depending on how intermediate directories are wildcarded. For example, consider following directories log, a, b and files c.log, d.log and e.log:

./
└── log/
    ├── a/
    │   ├── b/
    │   │   └── c.log
    │   └── d.log
    └── e.log

Wildcarding intermediate directories individually group:testers:glob:/logs/*/*/* will result in matching only at the bottom level directory /log/a/b/c.log (the files in intermediate-level directories are not matched).

Wildcarding intermediate directories with multiple stars group:testers:glob:/logs/**/* will result in matching files in all respective level directories: /log/e.log, /log/a/d.log and /log/a/b/c.log.

Consider another example demonstrating the power of execPath. In this scenario, a user has no rights to a certain datastore, as access to it is restricted by ACL in resource tree. However, the user has execution right on a script, which accesses this datastore. Now then, if the datastore has execPath blob rACL rule definition like:

execPath:/path/to/script.sx:glob:/*/logs/****/*.log

the user has access to protocol://datastore/logs/****/*.log files through execution of the script /path/to/script.sx.

Data Access Protocols

The access to data access protocols can be configured by assigning one of the following values to configuration key engine.da.protocol.<protocol> for the target protocol:

  • unmanaged - protocol targets can be specified arbitrarily by all SpectX users
  • managed - protocol targets can be defined only using data store located in /system/datastores (allowed only for users with Administrator role).
  • disabled - the protocol is disabled completely.

The policy is defined in the system configuration and therefore is applied system-wide.

The value of the <protocol> in the key name must conform to URI scheme standard and must be in lower case.

The default access mode is unmanaged.

Note

To prevent arbitrary access to local file system the default configuration defines file protocol as managed.

The sx protocol is not configurable, thus specifying protocol permission in configuration causes an error at startup.