Including Action Events

Beta Feature

This article is subject to change as the feature develops and we make improvements.

In this article we'll cover the main components of what's needed when writing a policy. To help with this, we'll be referencing the Monitor Authentications (MA) policy template that's available in HYPR Adapt. This template was built specifically to have the basic functionality needed to have a working Adapt policy.

Prerequisites

Writing an Adapt policy first requires knowledge in the language used to write the policies. Policies are written in a declarative language called Rego. The benefit of this language is that it makes reading and writing policy code easier. Before going through this guide, we recommend that you look through the documentation for Rego so that you have better context of what's happening in your policy code.

Action Events

A policy execution can request an action; e.g., notify security; call an external system; or send a text.

Requesting an Action from the Policy

The policy must return an actionEvent attribute. The contents of the actionEvent attribute will write to the Event ingestion queue as a new Event. This Event will be ingested/processed like any other.

Include an action Event:

• If you need a reference to your policy evaluation result in your app Events, the action Event can later be used to determine the result of a future policy evaluation

• To trigger other actions using an Signal Handler to process this event and perform the desired action

Below is an action Event we have defined in the policy:

actionEvent := {
  "eventName": "BLOCK_USER_ACTION_EVENT",
  "eventTags": ["RISK_ENGINE", "ADAPT", "ADMIN"],
  "machineUserName": input.events[0].machineUserName,
  "isSuccessful": true
} if {
	unsuccessfulAuthAttempt
    not userCurrentlyBlocked
    blockOnFailedEvaluation
} 

To create an action Event, create a document called actionEvent that will equal a custom Event based on a rule evaluation.

Mandatory Attributes

These must be returned by the policy:

• eventName: Can be any string. The preferred format is camelCase

• eventTags: String indicating the category of the event; for example: ACTION, AUTHENTICATION, REGISTRATION

Optional Attributes

• message: A string with a comment for logs

• source: A string indicating the origin of this event; the default value is supplied by HYPR PolicyId:$policyId

• The policy author may add any other attributes to the action Event to help with processing later at the Event Handler

If the rule conditions are met, this Event is included in our global input.events during the next policy evaluation for this entity. You may then access it like any other Event:

userCurrentlyBlocked if {
	some event in input.events
    withinTimeframe(event)
    event.eventName == "BLOCK_USER_ACTION_EVENT"
    blockOnFailedEvaluation
}

Policy Configuration and Placeholders

To make your policy easily configurable, you can use a policy configuration form and pass those values into your policy code. Below is the policy configuration for our MA policy:

Each field has a key assigned which is used for reference. The field key can be retrieved or set in the form editor:

fields:
  time_period: # Field key
    type: number
    required: true
    label: Authentication Time Period (Minutes)
    description: How far back from the time of evaluation to check for authentication attempts.
    defaultValue: 5
  block_on_failed_eval: # Field key
    type: switch
    label: Block User On Failed Authentication Attempt
    description: Prevent the user from logging in if they fail the policy evaluation.
    defaultValue: true

In the policy code, use %%field_key%% to indicate the area of the code that should be replaced with the associated configuration value.

For example, the line below:

blockOnFailedEvaluation := %%block_on_failed_eval%%

…will be changed to the following line before policy evaluation occurs:

blockedOnFailedEvaluation := true
// Will equal false if "Block User On Failed Authentication Attempt" is not enabled

Use the policy configuration form for mutable parts of your policy or for parts of your policy that should be manageable by those less comfortable with handling code.

Adapt Placeholders

Placeholders are an Adapt policy-specific feature and are not standard to the Rego policy language.