Splunk® User Behavior Analytics

Develop Custom Content in Splunk User Behavior Analytics

This documentation does not apply to the most recent version of Splunk® User Behavior Analytics. For documentation on the most recent version, go to the latest release.

Example: Create a new custom badge access model

In this example, we want to create some custom content that tracks badge access locations for users. The following tasks must be performed to complete this example.

  1. Create a content developer user account.
  2. Examine a raw event and identify the attributes to track.
  3. Create a custom cube.
  4. Create the rare events model.
  5. Trigger the model to create anomalies in test mode.
  6. Activate the custom model and migrate test anomalies.
  7. Create a threat rule using the new anomalies.
  8. View the new custom badge access threats.

Create a content developer user account

Create a user account with the Content_Developer role. This is the only Splunk UBA role with privileges to create custom content.

  1. Log in to Splunk UBA as an admin user.
  2. In Splunk UBA, select Maange > UBA Accounts
  3. Click New User Account.
  4. Enter a username such as contentdev.
  5. Enter and confirm the user's password.
  6. Select Content_Developer as the role for this user.
  7. Click OK.
  8. Log out of Splunk UBA.

Examine a raw event and identify the attributes to track

Suppose your company has multiple buildings in multiple sites equipped with Brivo badge access readers. In our example, we use the data from the badge readers and track information such as the name of the user and the location where the user attempted to gain access.

Below is a sample event from a Brivo badge access reader: 

{"actionTypeId": 2004, "user": {"id": 14572293, "suspended": false, "credentials": [{"id": 18796647, "credentialFormat": {"id": 304, "name": "HID Corporate 1000 48-bit"}, "referenceId": "70161", "accountId": 1542417, "size": 48, "effectiveFrom": "2019-08-08T03:40:27Z", "fieldValues": [{"id": 106, "value": "70161", "name": "card_number"}, {"id": 107, "value": "4340", "name": "facility_code"}], "encodedCredential": "4010f4022423"}], "groups": [{"id": 12971487, "name": "SF 250B - ALL ACCESS 24/7"}, {"id": 11454889, "name": "SF 250B - Garage"}], "lastName": "Manger", "firstName": "Louis", "customFields": [{"id": 578736, "value": "EMC", "fieldType": "TEXT", "fieldName": "Company"}, {"id": 589295, "fieldType": "TEXT", "fieldName": "Job Title"}, {"id": 578737, "fieldType": "TEXT", "fieldName": "Address 1"}, {"id": 578738, "fieldType": "TEXT", "fieldName": "Address 2"}, {"id": 587605, "value": "EMCbuildingmaintenance@yahoo.com", "fieldType": "TEXT", "fieldName": "Email"}, {"id": 589296, "fieldType": "TEXT", "fieldName": "Reason for Access"}]}, "description": "User Entry", "userId": 14572293, "objectName": "1F @ Brannan (main entrance)", "siteName": "250B Acme SF (Basement PNL)", "id": 1298420228, "occurred": "2019-08-08T03:40:27.831Z", "siteId": 12490054, "objectId": 12490246, "objectType": "ACCESS_POINT"}

In our example cube, we want to track the user name, user ID, site name, and entry location. In the raw event, we can find a userId field to extract, but there is no single field for user name. There are separate firstName and lastName fields. To get a better idea how to to define the attribute keys we need to extract the correct values and populate our cube, you can examine the existing badgeaccess cube in Splunk UBA.

  1. Make sure you are logged in to Splunk UBA as a user with content developer privileges.
  2. Select System > Cubes.
  3. In the URL, add ?system immediately following the host name or IP address. For example: 
    https://uba-001.example.com/?system#Y2FzcGlkYS5jdWJlcy5jdWJlRGV0YWlsc1ZpZXc=
  4. Select the badgeaccess cube to view its details.

Examine the existing badgeaccess cube in Splunk UBA to see how specific attributes and attribute keys. The following attributes and their keys are highlighted in the image. We will use the same attributes and keys later when we create a new cube:

  • The user ID is held by the userId attribute, which has the attribute key view.*.user.uuid.
  • The user name is held by the userName attribute, which has the attribute key view.*.user.
  • The name of the site is held by the siteName attribute, which has the attribute key event.attribute#siteName .
  • The entry location is held by the entryLocation attribute, which has the attribute key event.attribute#objectName.
  • A count of the number of unique events is kept using the event.format attribute key.

This screen image shows the details of the badgeaccess cube in Splunk UBA. The important elements are described in the surrounding text.

Create a custom cube

Perform the following tasks to create our custom cube.

  1. Log in to Splunk UBA as a user with Content_Developer privileges, such as contented, created earlier in this example.
  2. Select System > Cubes.
  3. Click New Cube.
  4. Configure the cube properties.
    1. Enter badgeAccessTracking as the name of the cube.
    2. Enter Track badge access per user as the description.
    3. Enter 1 as the version.
    4. Configure a retention interval of 3 months and a refresh interval of 1 hour.
    5. Leave Null as the view type, because Splunk UBA does not have any existing views related to badge access.
      This screen shot shows the first page of the new cube creation wizard. The fields on the screen are described in the text surrounding the image.
    6. Click Next.
  5. Configure the attributes to store in the cube.
    1. Enter the following attributes and relevant information. These are the attributes identified earlier in Examine a raw event and identify the attributes to track.
      Name Description Category Type Attribute Key Function
      userId User's ID. Dimension String view.*.user.uuid None
      userName User's Name. Dimension String view.*.user None
      siteName Name of the site. Dimension String event.attribute#siteName None
      entryLocation Location at the site where entry was attempted. Dimension String event.attribute#objectName None
      numEvents Total number of entry attempts. Measure Long event.format COUNT

      This screen shot shows the second page of the new cube creation wizard. The fields on the screen are described in the text surrounding the image.
    2. Click Next.
  6. Configure aggregation filters to drop invalid events. Use the following expression to drop any events that do not have an entry location: 
    entryLocation != null
  7. Click OK.


The new cube should appear on the custom cubes page in Splunk UBA.

This screen shows the Custom Cubes page in Splunk UBA. There is one custom cube shown on the page, called badgeaccesstracking.

Below is an example of the cube being populated with some data. 

day | userId    | userName         | siteName                      | entryLocation        | numEvents
----+-----------+------------------+-------------------------------+----------------------+-----------
1   | 14572293  | louis manager    | 250B Acme SF (Basement PNL)   | Elev CAB 2           | 3
1   | 14572239  | enrique manager  | 250B Acme SF (Basement PNL)   | Elev CAB 2           | 2
2   | 14572293  | louis manager    | 250B Acme SF (Basement PNL)   | Elev CAB 1           | 2
2   | 14572239  | enrique manager  | 250B Acme SF (Basement PNL)   | Elev CAB 2           | 2
3   | 14572293  | louis manager    | 250B Acme SF (Basement PNL)   | Elev CAB 1           | 3
3   | 14572239  | enrique manager  | 250B Acme SF (Basement PNL)   | Elev CAB 2           | 4
4   | 14572293  | louis manager    | 250B Acme SF (Basement PNL)   | Elev CAB 1           | 4
4   | 14572239  | enrique manager  | 250B Acme SF (Basement PNL)   | Elev CAB 2           | 3
4   | 14572293  | louis manager    | 250B Acme SF (Basement PNL)   | Basement S Stairway  | 1

Create the rare events model

Create a new rare events model.

  1. Make sure you are logged in to Splunk UBA as a user with Content_Developer privileges.
  2. Select System > Models.
  3. Click New Custom Model.
  4. Select Rare Events Model and select the Create new model radio button.
  5. Click Next.
  6. Select the cube we just created, called badgeAccessTracking, and verify the all the attributes are present. This screen shot shows the second page of the new model creation wizard. The fields on the screen are described in the text surrounding the image.
  7. Click Next.
  8. Configure the tracking features.
    1. Select entryLocation as the field and userName as the conditional. This means the model tracks the rarity of entryLocation for any given userName.
    2. Select userName to display as columns for evidence.
    3. Select userId as the participant. Generated anomalies with rare values and identical participants are grouped together. This screen shows the third page of the new model creation wizard. The fields on the screen are described in the text surrounding the image.
    4. Click Next.
  9. Configure the attribute display names. Enter a desired user-friendly name for each of the attributes used in the mode.
  10. Click Next.
  11. Configure the attributes for the model.
    1. Enter a model name that is be stored internally by Splunk UBA, such as BadgeAccessTracking.
    2. Enter a user-friendly name for the model, such as Example Badge Access Tracking.
    3. Enter a description for the model, such as This model tracks user access per site.
    4. Specify a version number for the model in the format x.x, such as 1.0.
    5. Click Next.
  12. Configure the model parameters.
    1. Enter 30 as the rare threshold, meaning that 1 occurrence out of 30 is considered rare.
    2. Enter 1 as the count threshold since we only defined one tracking feature (entryLocation as the field and userName as the conditional).
    3. Specify a new use case, such as ExampleRareBadgeAccess. No spaces are allowed in the use case name.
    4. Configure 3 months as the amount of time the model looks back when analyzing events. Since we configured the cube to store 3 months worth of data, configure the model look back at all 3 months worth of data.
    5. Click Next.
  13. Configure the attributes for the anomaly that this model generates.
    1. Specify an anomaly name, such as Example Rare Badge Access.
    2. Enter a description. For example, Rare badge access was detected.
    3. Select Badge Access as the category.
    4. Click Next.
  14. Customize the anomaly field display names.
  15. Click OK.

Look for a message in Splunk UBA indicating that the model was created successfully. Verify that the model exists on the Custom Models page.

This screen image shows the Custom Model page in Splunk UBA. There are four models listed, and the Example Badge Access Tracking model is highlighted.

Trigger the model to create anomalies in test mode

Trigger the model to make it run once, and generate anomalies in test mode.

  1. Make sure you are logged in to Splunk UBA as a user with content developer privileges.
  2. In Splunk UBA, select System > Models.
  3. Click Custom Models.
  4. Hover over the Example Badge Access Tracking model you just created, click the hamburger (The edit model icon) icon and select Trigger.
  5. Click OK to confirm that you want to trigger the model.

To see if the model generated any anomalies, perform the following tasks:

  1. In Splunk UBA, select Export > Anomalies.
  2. Select Actions > View Test Mode Anomalies.

If your model generated any anomalies, they are listed here.

This screen image shows the Test Mode Anomalies page with several Badge Access Tracking anomalies generated from our example model.

Activate the custom model and migrate test anomalies

Test mode anomalies are not consumed by any part of Splunk UBA. In order to make them accessible to threat rules and generate threats, activate the custom model and migrate the test mode anomalies to be live anomalies.

  1. Make sure you are logged in to Splunk UBA as a user with content developer privileges.
  2. In Splunk UBA, select System > Models.
  3. Click Custom Models.
  4. Hover over the Example Badge Access Tracking model you just created, click the hamburger (The edit model icon) icon and select Activate.
  5. Select Move anomalies to Active Mode to migrate the test mode anomalies generated by this model to live anomalies.
  6. Click OK to confirm that you want to activate the model.

Verify that the test mode anomalies are migrated.

  1. Select Explore > Anomalies.
  2. Verify that your anomalies appear on this screen.

This screen image shows the Anomalies table with several Example Badge Access Tracking anomalies generated from our example model.

Create a threat rule using the new anomalies

Perform the following tasks to create a new threat rule using the new badge access anomaly. See Create a custom threat with a threat rule for more information about the workflow.

  1. In Splunk UBA, select Explore > Threats.
  2. Click on the Custom Threats (The custom threats icon) icon.
  3. Click New Threat Rule.
  4. Select User as the participant.
  5. Click Next.
  6. Configure the User Filters.
    1. Configure an anomaly count of greater than or equal to 1.
    2. Click Next.
  7. Configure the Threat Conditions.
    1. Select Example Rare Badge Access as the anomaly type from the drop-down list and enter a count of 1.
    2. Specify an Anomalies Interval of 1 and a Max Threat Duration of 30 days.
      This screen image shows Step 3 of 6 in the New Threat Rule dialog window. The important fields are described in the text immediately preceding the image.
    3. Click Next.
  8. Configure the Anomaly Processing.
    1. By default, threat rules process anomalies starting from when it is activated and going forward. Click Process anomalies in the past and configure a past duration of 30 days. This means that the rule processes anomalies from this point forward, and also looks back on anomalies generated in the past 30 days.
    2. Click Next.
  9. Configure threats generated by this threat rule.
    1. Use the slider to select a custom score for the threat, such as 5.
    2. Click Create a New Custom Threat Type and enter a threat name, such as Example Rare Badge Access.
    3. Select Internal as the threat category, because we are examining the behavior of internal users.
    4. Enter a description for the threat, such as Suspicious badge activity by a user.
      This screen image shows Step 5 of 6 in the New Threat Rule dialog window. The important fields are described in the text immediately preceding the image.
    5. Click Next.
  10. Enter a name and description for the rule. An example name might be Example Suspicious or Rare Badge Access.
  11. Click OK.
  12. Verify that your custom threat rule appears on the Custom Threats page.
    This screen image shows the Suctom Threats page in Splunk UBA. A custom threat named Example Suspicious or Rare Badge Access is highlighted.
    In this example, we can see that our threat rule has generated three threats.

View the new custom badge access threats

Perform the following tasks to verify that the threats are visible to all users on this Splunk UBA system.

  1. Log in to Splunk UBA as a user who is not a content developer, such as an admin.
  2. Select Threats from the Splunk UBA home page, or select Manage > Threats.
  3. Verify that the new threat is visible in the list of threats. In our example, our new threat is called Example Rare Badge Access.
  4. Click on the threat name Example Rare Badge Access.

This screen image shows the Threats Table with mutlple Example Rare Badge Access threats.

Last modified on 06 January, 2020
Edit anomaly scoring rules  

This documentation applies to the following versions of Splunk® User Behavior Analytics: 5.0.0

Acrobat logo Download manual
Acrobat logo Download this page

Was this topic useful?







You must be logged into splunk.com in order to post comments. Log in now.

Please try to keep this discussion focused on the content covered in this documentation topic. If you have a more general question about Splunk functionality or are experiencing a difficulty with Splunk, consider posting a question to Splunkbase Answers.

0 out of 1000 Characters