Global Policies

Global policies govern sensitive data classified with labels and tags in the datamap, regardless of where (repository, schema, table, column etc) it exists. This allows an administrator to ensure that uniform policies are applied for the same kind of data (e.g., credit card numbers) regardless of where such data is stored. Thus these policies apply to all repositories provided that the data in the repository has been classified appropriately.

Managing Global Policies

To create a new global policy or to manage existing ones, in the Cyral Control Plane UI, click Global Policies.

Creating a New Global Policy

To create a new global policy, click Add Policy.

1. In the Describe panel:

   • Give your policy a name and an optional description.
   • Optionally, you can add one or more Policy Type tags to the policy. To do this, type your tag name in the field below Policy Types and then click Add.
   • Click Next.

2. The next screen will have a text area where you can enter (or paste) the policy document in JSON format. The policy format is described in the following section. You can also choose to enable the policy in the test mode - this causes the policy violations to be reported but the policy is not actually enforced. Click Add Policy to save the policy.

Your policy is enabled by default, which means it takes effect immediately. To manage, disable, and enable your policy, use its card in the Global Policies panel.

Edit, enable, disable or delete a repo-level policy

To edit, enable, disable or delete a global policy, click on the card for the relevant policy in the Global Policies panel. Now click Configure and choose Edit, Enable, Disable or Delete.

Policy Structure

Global policies are specified using a JSON policy document that must conform to a well-defined schema. The policy document for a global policy is a JSON object with the following top level fields.

governedData (required): This element specifies the set of data labels and/or data tags that the policy governs. The data labels and tags specified here may be glob patterns with wildcard characters such as * and ?. The complete syntax for supported glob patterns can be found here. An example value for this element could be:

"governedData": {
    "labels": ["CCN", "SSN"],
    "tags": ["PII"]
}

In the example above, the policy would govern fields labeled as CCN or SSN or with any other label that is tagged as PII.

governedOperations: This element specifies the data operations (or access types) that are governed by this policy. The value is a list of operations from among "read", "update", "delete", and "insert". For example, the value

"governedOperations": ["read", "update"]

specifies that only read and update operations are governed by the policy, that is the policy will not apply if the governed data items are deleted or inserted.

If the governedOperations data is not specified in a policy, it signifies that all the four operation types are governed by the policy.

readRules: rules that specify under what conditions the governed data can be read and with what constraints (e.g., with masking applied or with row limits).

deleteRules: rules that specify when the governed data can be deleted.

updateRules: rules that specify when the governed data can be updated.

insertRules: rules that specify when the governed data can be inserted.

info

Rules for an operation (read, delete etc) can only be specified if the operation is governed by the policy. That is, governedOperations must either contain the relevant operation, or be unspecified (which signifies that all operations are governed by the policy).

Rule Structure and Policy Evaluation

A rule consists of two parts:

conditions (required): this is a list of conditions all of which must be true for the rule to apply. Note that if a rule has no conditions (i.e., the value of the conditions field is an empty list), it will trivially apply. This can be useful to create a default or catch-all rule that defines the access constraints when none of the other rules apply.

constraints (required): this is the set of constraints that are imposed by the rule on access. Constraints can be zero or more of: impose a rate limit, impose a row limit, mask the data, and raise an alert. Note that if the value of the constraints field is {}, it means that no constraints on access are imposed by the rule.

The evaluation of a policy proceeds as follows.

• The policy is applicable and evaluated only if an attribute with a data label or data tag that is governed by the policy is accessed in the request.
• Depending on the attribute access type, the rules for read, update, or delete are evaluated, in the order in which they are specified in the policy.
• Rule evaluation stops when the first rule whose conditions are all satisfied is seen. In such a case, the result of the policy is to allow access subject to the constraints specified in the matching rule.
• If no rule matches for the access type (or if there are no rules at all for the access type), access is denied by the policy, and the query will be blocked.

Rule conditions

As mentioned earlier, each rule may have some conditions attached to it and each of these conditions must evaluate to true for the rule to match. A condition is an object with the following fields.

attribute: This field denotes the JSON path of a field in the data activity log. The field value can be a string or a list of strings. Some examples of valid values for this field are:

• identity.endUser: the username of the end user (string)
• identity.endUserEmail: the end user email address (string)
• identity.userGroups: the list of SSO groups that the user belongs to (list of strings).
• identity.repoUser: the database account used to log in (string)

The list of attributes that can be referenced in conditions, along with their types, is given in this section.

operator: the value of this field must be one of "equals", "is-in", "contains", "intersects", and "matches".

value: the value for this field can be a string or a list of strings.

negated: this is a boolean value (default false). If true, the result of the operator evaluation is negated. That is, negation causes the condition's truth value to be reversed.

caseSensitive: boolean value (default false) indicating whether string matching should be performed case sensitively.

A condition should be read as "attribute operator value". That is, the attribute value is the left operand for the operator, while the value in the condition is its right operand.

For each of the operators, the value (the second operand) is treated as a set (a set containing a single element if the value was a string). The operators behave as follows.

• Attribute equals Value is true if either:
  • The type of Attribute is a string and it is equal to any of the strings in Value, OR
  • The type of Attribute is a list of strings and it is the same set as Value.
• Attribute is-in Value is true if either:
  • The type of Attribute is a string and it is equal to any of the strings in Value, OR
  • The type of Attribute is a list of strings and it is a subset of Value. Note that for attributes of type string, both equals and is-in have the same behavior.
• Attribute contains Value is true if the value of Attribute (treated as a singleton set if it is a string) is a superset of (contains every element of) Value.
• Attribute intersects Value is true if the value of Attribute (treated as a singleton set if it is a string) has at least one element in common with Value.
• Attribute matches Value is true if: the type of Attribute must be a string and it matches one or more of the glob patterns in Value.

Examples

• The condition below would be true if the username of the end user is either “user1” or “user2” (case insensitive match).

{
    "attribute": "identity.endUser",
    "operator": "equals",
    "value": ["user1", "user2"]
}

• The following condition would be true if the end user belongs to both group1 and group2 (possibly in addition to other groups).

{
  "attribute": "identity.userGroups",
  "operator": "contains",
  "value": ["group1", "group2"]
}

• The following condition would be true if the end user belongs to at least one of group1 and group2 (possibly in addition to other groups).

{
  "attribute": "identity.userGroups",
  "operator": "intersects",
  "value": ["group1", "group2"]
}

• The following condition would be true if the end user belongs to both groups group1 and group2, and to no other groups.

{
  "attribute": "identity.userGroups",
  "operator": "equals",
  "value": ["group1", "group2"]
}

• The following condition would be true if the user email does not end in either of @acme.com and @example.com.

{
  "attribute": "identity.endUserEmail",
  "operator": "matches",
  "negated": true,
  "value": ["*@acme.com", "*@example.com"]
}

Rule Constraints

The rule constraints object has the following fields. Note that all fields are optional. If none of them are present, access is permitted without any constraints.

maxRows: The value of this field is a positive integer denoting the row limit on the response.

rateLimit: The value of this field denotes the number of rows permitted to be retrieved or affected by the user per hour.

mask: This field specifies masking to be performed on the field value before it is returned to the user. Its value is an object with fields:

• function: the masking function to be used. Valid values are “null”, “constant”, “format-preserving”, or the name of a custom mask function prefixed with custom:.
• args: list of any additional arguments needed by the mask function. The constant function requires a single argument. The null and format-preserving functions do not require any arguments.

alert: an alert is raised for the query (though access is permitted). The value of this field is an object with fields message (string denoting alert message) and severity. The valid values for severity are "low", "medium", and "high".

info

The mask constraint can only be specified in readRules and the rateLimit constraint can only be specified in readRules, updateRules, and deleteRules.

Default Policies

The policies described above are targeted towards or govern access to specific data labels. If no policy governs a given label, all accesses to the label are allowed. This behavior can be changed by defining a default policy that applies to all accesses that are not governed by any of the targeted policies. In such default policies, the value of the element governedData is specified simply as "default", and the rest of the policy structure is exactly as described above. As an example, consider the following default policy.

{
  "governedData": "default",
  "governedOperations": ["read"],
  "readRules": []
}

This policy will apply to read access to any label for which the read operation is not governed by any of the targeted policies. As can be seen, this policy denies read to all users, hence it implements a "deny by default" security model for read accesses.

A Complete Policy Example

The following policy governs access to labels CCN, EMAIL, and SSN, and any other fields tagged as PII. It allows read access to all users but the data is masked for all users except those in the admin group. Unrestricted read access is also allowed to a web application that uses the database account webapp. Any data changes (deletes, inserts, or updates) are only permitted to the database account webapp.

{
  "governedData": {
    "labels": ["CCN", "EMAIL", "SSN"],
    "tags": ["PII"]
  },
  "readRules": [
    {
      "conditions": [
        {
          "attribute": "identity.userGroups",
          "operator": "contains",
          "value": "admin"
        }
      ],
      "constraints": {}
    },
    {
      "conditions": [
        {
          "attribute": "identity.repoUser",
          "operator": "equals",
          "value": "webapp"
        }
      ],
      "constraints": {}
    },
    {
      "conditions": [],
      "constraints": {
        "mask": {
          "function": "constant",
          "args": ["REDACTED"]
        }
      }
    }
  ],
  "updateRules": [
    {
      "conditions": [
        {
          "attribute": "identity.repoUser",
          "operator": "equals",
          "value": "webapp"
        }
      ],
      "constraints": {}
    }
  ],
  "deleteRules": [
    {
      "conditions": [
        {
          "attribute": "identity.repoUser",
          "operator": "equals",
          "value": "webapp"
        }
      ],
      "constraints": {}
    }
  ],
  "insertRules": [
    {
      "conditions": [
        {
          "attribute": "identity.repoUser",
          "operator": "equals",
          "value": "webapp"
        }
      ],
      "constraints": {}
    }
  ]
}

The policy above has three read rules. The first applies only if the user is a member of the admin group and allows access without any constraints. The second rule applies if the database account webapp is used to connect and also allows access without constraints. The third rule has no conditions and hence applies to all users. This rule specifies a masking constraint that replaces any of the governed fields with the constant value REDACTED. Since the rules are evaluated in sequence and evaluation stops when the first matching rule is found, the effect of these rules is that members of the admin group and any application using the webapp database account will see the actual data while all other users will see the masked data.

There is just one update rule and similar delete and insert rules. These rules have a condition requiring the database account to be webapp and no constraints. For all other users, this rule will not match and hence update, delete, or insert access will be denied.

Attributes that can be referenced in Conditions

The table below lists the attributes that can be referenced in policy conditions, along their types and a brief description. Please see activity log specification for details on these attributes.

Attribute	Type	Description
client.host	string	IP address of the client
client.applicationName	string	Client application name (if available)
identity.endUser	string	Username of the authenticated end user
identity.endUserEmail	string	Email address of the authenticated end user
identity.repoUser	string	Database account used for authentication
identity.dbRole	string	Database role if available
identity.group	string	(Deprecated) The user's SSO group (if any) that matched the access rule
identity.userGroups	set	Set of SSO groups that the user belongs to
repo.id	string	ID of the repository being accessed
repo.name	string	Name of the repository being accessed
repo.type	string	Type of the repository being accessed
repo.host	string	IP address or hostname of the repository being accessed
request.statement	string	The database statement issued
request.statementType	string	The type of the request statement (e.g., SELECT)
request.cursorStatement	string	The statement corresponding to this cursor fetch
request.cursorStatementType	string	The prepared statement being executed in this request
request.preparedStatement	string	The prepared statement being executed in this request
sidecar.id	string	ID of the sidecar used to access the repository
sidecar.name	string	Name of the sidecar used to access the repository
cyralContext.user	string	The user field in cyral context
cyralContext.group	string	The user group name specified in cyral context
cyralContext.serviceName	string	The service name specified in cyral context
cyralContext.attributes.X	string	Value of arbitrary attribute X specified in cyral context