Compliance API

Compliance API Reference

Compliance API Examples

Create the bearer_token and store in a file in a secure local directory with 0600 permissions.

Types of Compliance Policies

Compliance Posture is measured against user-defined rule sets called Compliance Policies.

Compliance policies are created once and then Assets can be tested against them at any point in time.

For instance, a policy might state that “Maintenance Alarm Events must be answered with a Maintenance Report Event recorded in 72 hours”.

This creates a Compliance Policy object in the system against which any asset can be tested as needed.

RKVST allows users to define Compliance Policies of the following types:

COMPLIANCE_SINCE

This Compliance Policy checks if the time since the last occurence of a specific Event Type has elapsed a specified threshold.

For example “Time since last Maintenance must be less than 72 hours”:

{
    "compliance_type": "COMPLIANCE_SINCE",
    "description": "Maintenance should be performed every 72h",
    "display_name": "Regular Maintenance",
    "asset_filter": [
        { "or": ["attributes.arc_location_identity:locations/5eef2b71-35c1-4376-a166-6c64bfa72f4b"]}
    ]
    "event_display_type": "Maintenance Performed",
    "time_period_seconds": "259200"
}
AttributeDescription
event_display_typeType of event we want to check with this compliance policy
time_period_secondsThe maximum amount of time allowed since a specified event type last occurred in seconds

COMPLIANCE_CURRENT_OUTSTANDING

This Compliance Policy will only pass if there is an associated answering event addressing a specified outstanding event.

To correlate events define the attribute arc_correlation_id in the Event Attributes and set it to the same value on each pair of events that are to be associated.

For example defining pairs of Events like Maintenance Request and Maintenance Performed:

{
    "compliance_type": "COMPLIANCE_CURRENT_OUTSTANDING",
    "description": "There should be no outstanding Maintenance Requests",
    "display_name": "Outstanding Maintenance Requests",
    "asset_filter": [
        { "or": ["attributes.arc_location_identity:locations/5eef2b71-35c1-4376-a166-6c64bfa72f4b"]}
    ]
    "event_display_type": "Maintenance Requests",
    "closing_event_display_type":  "Maintenance Performed"
}
AttributeDescription
event_display_typeType of event that should be addressed by the event defined in closing_event_display_type
closing_event_display_typeType of event addressing the event defined in event_display_type

COMPLIANCE_PERIOD_OUTSTANDING

This Compliance Policy will only pass if the time between a pair of correlated events did not exceed the defined threshold.

To correlate events define the attribute arc_correlation_id in the Event Attributes and set it to the same value on each pair of events that are to be associated.

For example, a policy checking that the time between Maintenance Request and Maintenance Performed Events does not exceed the maximum 72 hours:

{
    "compliance_type": "COMPLIANCE_PERIOD_OUTSTANDING",
    "description": "There should be no outstanding Maintenance Requests",
    "display_name": "Outstanding Maintenance Requests",
    "asset_filter": [
        { "or": ["attributes.arc_location_identity:locations/5eef2b71-35c1-4376-a166-6c64bfa72f4b"]}
    ]
    "event_display_type": "Maintenance Requests",
    "closing_event_display_type":  "Maintenance Performed",
    "time_period_seconds": "259200"
}
AttributeDescription
event_display_typeType of event that should be addressed by the event defined in closing_event_display_type
closing_event_display_typeType of event addressing the event defined in event_display_type
time_period_secondsMaximum amount of time that can elapse between associated events in seconds

COMPLIANCE_DYNAMIC_TOLERANCE

This Compliance Policy will only pass if the time between a pair of correlated events did not exceed the defined variability.

To correlate events define the attribute arc_correlation_id in the Event Attributes and set it to the same value on each pair of events that are to be associated.

For example, a policy checking that the time between Maintenance Request and Maintenance Performed Events in the last week does not exceed a variability of 0.5 standard deviations around the mean:

{
    "compliance_type": "COMPLIANCE_DYNAMIC_TOLERANCE",
    "description": "Average time between Maintenance Requested/Performed"
    "display_name": "outlying Maintenance Requests",
    "asset_filter": [
        { "or": ["attributes.arc_location_identity:locations/5eef2b71-35c1-4376-a166-6c64bfa72f4b"]}
    ]
    "event_display_type": "Maintenance Requests",
    "closing_event_display_type": "Maintenance Performed",
    "dynamic_window": 604800,
    "dynamic_variability": 0.5
}
AttributeDescription
event_display_typeType of event that should be addressed by the event defined in closing_event_display_type
closing_event_display_typeType of event addressing the event defined in event_display_type
dynamic_windowNumber of seconds in the past - only events in this time window are considered.
dynamic_variabilityExceeding this number of standard deviations from the mean will cause compliance to fail for a particular pair of matching events.

COMPLIANCE_RICHNESS

This Compliance Policy will only pass if the assertions conducted on an attribute value pass.

An assertion is comprised of: an attribute name, a comparison value and an operator to compare with; for example rad<7.

The operator can be one of six relational operators: equal to, not equal to, greater than, less than, greater than or equal to, less than or equal to; [=|!=|>|<|>=|<=].

Assertions are comprised of two lists, an inner list and outer list. The inner list states that, if any of the assertions pass, then the list is compliant (OR logic). For example:

{“or”: [“rad<7”, “rad=10”]}. 

The outer list states that, all inner lists need to be compliant in order for the policy to be compliant (AND logic).

Compliance is a signal, not a perfect answer. Therefore equivilence of floats is exact, not approximate.

{
    "compliance_type": "COMPLIANCE_RICHNESS",
    "description": "Rad level is less than 7"
    "display_name": "Rad limit",
    "asset_filter": [
        { "or": ["attributes.arc_location_identity:locations/5eef2b71-35c1-4376-a166-6c64bfa72f4b"]}
    ],
    "richness_assertions": [
        { "or": ["rad<7"]}
    ],
}
AttributeDescription
richness_assertionsThe assertions to be made, against asset attributes, to check if the asset is compliant.

Compliance Policy Creation

Create a Policy with:

curl -v -X POST \
    -H "@$BEARER_TOKEN_FILE" \
    -H "Content-type: application/json" \
    -d "@/path/to/jsonfile" \
    https://app.rkvst.io/archivist/v1/compliance_policies

Using data from /path/to/jsonfile in the format described in Types of Compliance Policies.

Sample response:

{
    "identity": "compliance_policies/6a951b62-0a26-4c22-a886-1082297b063b",
    "compliance_type": "COMPLIANCE_CURRENT_OUTSTANDING",
    "description": "There should be no outstanding Maintenance Requests",
    "display_name": "Outstanding Maintenance Requests",
    "asset_filter": [
        { "or": ["attributes.arc_location_identity:locations/5eef2b71-35c1-4376-a166-6c64bfa72f4b"]}
    ]
    "event_display_type": "Maintenance Requests",
    "closing_event_display_type":  "Maintenance Performed",
    "time_period_seconds": "259200"
}

Checking Compliance

The compliancev1 endpoint reports on the status of an Asset’s Compliance with Compliance Policies.

Query the endpoint:

curl -v -X GET \
    -H "@$BEARER_TOKEN_FILE" \
    https://app.rkvst.io/archivist/v1/compliance/assets/6a951b62-0a26-4c22-a886-1082297b063b

or if determining compliance at some historical date:

curl -v -X GET \
    -H "@$BEARER_TOKEN_FILE" \
    https://app.rkvst.io/archivist/v1/compliance/assets/6a951b62-0a26-4c22-a886-1082297b063b?compliant_at=2019-11-27T14:44:19Z

The response is:

{
    "compliant": true,
    "compliance": [
        {
            "compliance_policy_identity": "compliance_policies/0000-0000-000000000-00000000",
            "compliant": true,
            "reason": ""
        }
    ],
    "compliant_at": "2019-11-27T14:44:19Z"
}

Compliance OpenAPI Docs

get  /archivist/v1/compliance/assets/{uuid}

List all compliance status relevant to an asset

Description:

{
  "compliance": [
    {
      "compliance_policy_identity": "compliance_policies/0000-0000-000000000-00000000",
      "compliant": false
    }
  ],
  "compliant": false,
  "compliant_at": "2019-11-27T14:44:19Z"
}
Response ParameterTypeDescription
compliancearraysimple compliance status against a compliance policy.
compliantbooleanoverall compliance status for the asset
compliant_atstringtime at which compliance is determined
next_page_tokenstringToken to retrieve the next page of results or empty if there are none.
ResponsesDescription
200A successful response.
206The number of compliance statements exceeds the servers limit.
401Returned when the user is not authenticated to the system.
403Returned when the user is not authorized to access the requested resource.
404Returned when the asset with the id does not exist.
429Returned when a user exceeds their subscription’s rate limit for requests.
defaultAn unexpected error response.

get  /archivist/v1/compliance_policies

Description:

{
  "compliance_policies": [
    {
      "asset_filter": [
        {
          "or": [
            "attributes.arc_location_identity:locations/5eef2b71-35c1-4376-a166-6c64bfa72f4b"
          ]
        }
      ],
      "compliance_type": "COMPLIANCE_SINCE",
      "description": "sample compliance policy",
      "display_name": "my compliance policy",
      "event_display_type": "tracked event",
      "identity": "compliance_policies/463fab3a-bae5-4349-8f76-f6454da20c9d",
      "time_period_seconds": 86400
    }
  ],
  "next_page_token": "NDYzZmFiM2EtYmFlNS00MzQ5LThmNzYtZjY0NTRkYTIwYzlkCg=="
}
Response ParameterTypeDescription
compliance_policiesarraycompliance policy
next_page_tokenstring
ResponsesDescription
200A successful response.
401Returned when the user is not authenticated to the system.
403Returned when the user is not authorized to access the requested resource.
404Returned when the asset with the id does not exist.
429Returned when a user exceeds their subscription’s rate limit for requests.
defaultAn unexpected error response.

post  /archivist/v1/compliance_policies

Description:

{
  "asset_filter": [
    {
      "or": [
        "attributes.arc_location_identity:locations/5eef2b71-35c1-4376-a166-6c64bfa72f4b"
      ]
    }
  ],
  "compliance_type": "COMPLIANCE_SINCE",
  "description": "Ensure Maintenance is performed daily",
  "display_name": "Daily Maintenance",
  "event_display_type": "Maintenance Performed",
  "time_period_seconds": 86800
}
ParameterTypeDescription
asset_filterarrayFilter
closing_event_display_typestringthis is the correlated event type
compliance_typepolicy type
descriptionstringCustomer description of the compliance policy.
display_namestringdisplay name
dynamic_variabilitynumbernumber of standard deviations - required for DYNAMIC_TOLERANCE
dynamic_windowstringvalid period for policy - required for DYNAMIC_TOLERANCE
event_display_typestringthis is the target event_display_type - always required
richness_assertionsarrayFilter
time_period_secondsstringtime delta - required for SINCE and PERIOD_OUTSTANDING

{
  "asset_filter": [
    {
      "or": [
        "attributes.arc_location_identity:locations/5eef2b71-35c1-4376-a166-6c64bfa72f4b"
      ]
    }
  ],
  "compliance_type": "COMPLIANCE_SINCE",
  "description": "Ensure Maintenance is performed daily",
  "display_name": "Daily Maintenance",
  "event_display_type": "Maintenance Performed",
  "identity": "compliance_policies/463fab3a-bae5-4349-8f76-f6454da20c9d",
  "time_period_seconds": 86800
}
Response ParameterTypeDescription
asset_filterarrayFilter
closing_event_display_typestring
compliance_type
descriptionstring
display_namestring
dynamic_variabilitynumber
dynamic_windowstring
event_display_typestring
identitystring
richness_assertionsarrayFilter
time_period_secondsstring
ResponsesDescription
200A successful response.
401Returned when the user is not authenticated to the system.
402Returned when the user’s quota of compliance policies has been reached.
403Returned when the user is not authorized to access the requested resource.
404Returned when the asset with the id does not exist.
429Returned when a user exceeds their subscription’s rate limit for requests.
defaultAn unexpected error response.

delete  /archivist/v1/compliance_policies/{uuid}

Description:

{
  "asset_filter": [
    {
      "or": [
        "attributes.arc_location_identity:locations/5eef2b71-35c1-4376-a166-6c64bfa72f4b"
      ]
    }
  ],
  "compliance_type": "COMPLIANCE_SINCE",
  "description": "Ensure Maintenance is performed daily",
  "display_name": "Daily Maintenance",
  "event_display_type": "Maintenance Performed",
  "identity": "compliance_policies/463fab3a-bae5-4349-8f76-f6454da20c9d",
  "time_period_seconds": 86800
}
Response ParameterTypeDescription
asset_filterarrayFilter
closing_event_display_typestring
compliance_type
descriptionstring
display_namestring
dynamic_variabilitynumber
dynamic_windowstring
event_display_typestring
identitystring
richness_assertionsarrayFilter
time_period_secondsstring
ResponsesDescription
200A successful response.
401Returned when the user is not authenticated to the system.
403Returned when the user is not authorized to access the requested resource.
404Returned when the asset with the id does not exist.
429Returned when a user exceeds their subscription’s rate limit for requests.
defaultAn unexpected error response.

get  /archivist/v1/compliance_policies/{uuid}

Description:

{
  "asset_filter": [
    {
      "or": [
        "attributes.arc_location_identity:locations/5eef2b71-35c1-4376-a166-6c64bfa72f4b"
      ]
    }
  ],
  "compliance_type": "COMPLIANCE_SINCE",
  "description": "Ensure Maintenance is performed daily",
  "display_name": "Daily Maintenance",
  "event_display_type": "Maintenance Performed",
  "identity": "compliance_policies/463fab3a-bae5-4349-8f76-f6454da20c9d",
  "time_period_seconds": 86800
}
Response ParameterTypeDescription
asset_filterarrayFilter
closing_event_display_typestring
compliance_type
descriptionstring
display_namestring
dynamic_variabilitynumber
dynamic_windowstring
event_display_typestring
identitystring
richness_assertionsarrayFilter
time_period_secondsstring
ResponsesDescription
200A successful response.
401Returned when the user is not authenticated to the system.
403Returned when the user is not authorized to access the requested resource.
404Returned when the asset with the id does not exist.
429Returned when a user exceeds their subscription’s rate limit for requests.
defaultAn unexpected error response.

get  /archivist/v1/compliance_policies:openapi

Get OpenAPI spec for Compliance

Description: Get OpenAPI v2.0 spec for Compliance

ResponsesDescription
200A successful response.
401Returned when the user is not authenticated to the system.
429Returned when a user exceeds their subscription’s rate limit for requests.
defaultAn unexpected error response.

get  /archivist/v1/compliance_policies:openapi-ui

Get OpenAPI UI for Compliance

Description: Get OpenAPI v2.0 UI for Compliance

ResponsesDescription
200A successful response.
401Returned when the user is not authenticated to the system.
429Returned when a user exceeds their subscription’s rate limit for requests.
defaultAn unexpected error response.

Edit this page on GitHub