Diagnostics Overview

Diagnostics allows Entitlement Systems to self-introspect, identify, and resolve possible problems with your Entitlements object model. Diagnostics consists of a collection of Rego rules, each implementing one diagnostic.

Diagnostics are intended to help answer questions like “Why can't Alice read the finance document?” or to help understand subtle issues with your Policy as Data.

Diagnostics have the following objectives:

• Determine if the data in the Entitlements object model is formatted correctly.
• Provide insight into why a particular request was allowed or denied.
• Surface matters likely need the policy author's attention within their Entitlements System.

Diagnostics Results

The diagnostics results include Severity Level, Relevance, Message, Recommendation, and Context. Recommendation and Context are omitted if they are not applicable.

Severity Level

Each diagnostic reports a severity level based on its findings. The three levels of severity are:

• Problem - indicates there is a problem that needs to be addressed.
• Warning - indicates there might be a problem, and user investigation is recommended.
• OK - indicates that no problem was detected.

There is an additional “SKIP” severity level, which is used to indicate the diagnostic could not run. This can happen if the user has disabled a diagnostic or if it is missing some prerequisite information, such as an input document.

Relevance

Diagnostics are divided into relevance categories for specific use cases. The three relevance categories are:

• ENTZ - diagnostics that are relevant to the Entitlements System, for example validating data provided by the user follows the schema prescribed by the entitlements object model.
• RBAC - diagnostics which are relevant to Role Based Access Control (RBAC) use cases of Entitlements.
• ABAC - diagnostics which are relevant to Attribute Based Access Control (ABAC) use cases of Entitlements.

Message

Message describes what the diagnostic did. For example, “Check Resource and Action for Roles” or “Ensure subject has attributes”.

Recommendation

Recommendation describes what action or actions should be taken to resolve any issues discovered through diagnostics.

Context

The context field exposes free-form data provided by the diagnostic itself. This data is intended to help you understand what the diagnostic discovered. For example, in a diagnostic that makes sure a subject has attributes, the context field might show what attributes were bound to the subject.

Input Document

An input document can optionally be provided, which will enable some diagnostics to provide more detailed information relevant to that specific input. This can be helpful when trying to debug a particular request, in addition to the overall system state. You must provide an input document if you are interested in understanding why a particular RBAC or ABAC authorization request did not behave as expected.

note

For diagnostics to provide value, it is highly recommended to provide an input document specific for what you need to diagnose.

The format of the Entitlements input document is:

  "action": "CREATE",
  "context": {
    "channel": "API-MOBILE-BROWSER",
    "location": "China"
  },
  "groups": [
    "group1",
    "group2"
  ],
  "jwt": "jwt token",
  "resource": "aResource:action",
  "resource-attributes": {
    "attr1": "value1",
    "attr2": "value2"
  },
  "roles": [
    "aRole1",
    "aRole2"
  ],
  "subject": "aSubject",
  "subject-attributes": {
    "attr1": "value1",
    "attr2": "value2"
  }
}

Diagnostics Examples

The following examples show how Diagnostics works.

Example 1

The following is an Entz example with the Diagnostic validating ‘data.object.service_accounts’. In this example, ‘data.object.service_accounts’ is empty and Diagnostics generates a warning and provides a recommendation on how to resolve the issue.

Message Check data.object.service_accounts. 'data.object.service_accounts' exists, but is empty.

Recommendation Modify object.rego to ensure data.object.service_accounts contains the expected data.

Example 2

The following is an RBAC example with the Diagnostic validating Check Resource and Action for Roles. In this example, the status is OK. The Diagnostic displays a message and context.

Message Check Resource and Action for Roles. Found 3 extant and 0 dangling resources across all roles. Found 3 extant and 0 dangling actions across all roles.

Example 3

In this example a typo is present in the object data for an Entitlements System. A role that provides access to a resource is bound to the store-manager group, but the actual ID of the group is store-managers. Diagnostics can help detect this problem through the “Check the Subjects for Role Bindings” diagnostic.

This example uses the following input document:

  "subject": "alice",
  "resource": "/cars/car5",
  "action": "PUT"
}

The “Check the Subjects for Role Bindings” reports the following:

Message: Found 0 role bindings with no subject, and 1 with dangling subjects.

Recommendation: Check data.object.role_bindings. Some of your roles directly bind to the subject by their IDs, but those subject IDs don't correspond to extant users, groups, or service accounts.

Context:

  "dangling_subjects": {
    "car-updaters": [
      "store-manager"
    ]
  },
  "no_subjects": []
}

This can help identify the store-manager group added to the car-updaters role might not have been the correct one, because the diagnostic is telling us that the store-manager subject is bound to a role, but does not exist elsewhere in the object data.

Example 4

In this example, the request subject is incorrect. A legacy system was converted to uppercase when it was actually lowercase in the Entitlements object data.

Diagnostics can help detect the error in the "Check Subject Roles” diagnostic. In this example, the following message is reported:

Subject 'ALICE' has no roles.

Recommendation Check object.rego to ensure that there are role bindings that apply to the subject.

This tells us that the subject in the request has no roles bound to it. In an RBAC use case, a subject with no bound roles will almost certainly be unable to access any resource with any action.

Additionally, the “Check Subject Exists” role will inform us that the subject in question does not exist with the following message:

Subject 'ALICE' is not valid.

Recommendation Check the source of the request, and ensure it is properly defining the 'subject' field.

Using Diagnostics

The following steps are used to run Diagnostics.

1. Login to Styra DAS.
2. Select an Entitlements System.
3. Click Diagnostics.
4. (Optional) Populate Input (the Input Document) to diagnose issues related to a specific request.
5. Click Run Diagnostics. The diagnostics results are displayed.