Add custom attributes to your HR data

Enrich your HR data by adding custom attributes. You can use custom attributes to filter users in Splunk UBA and create custom anomaly action rules using your custom attributes. You can create or modify your custom attributes as needed, and your changes will be reflected in the system the next time your HR data is updated.

See Get HR data into Splunk UBA to see the HR data fields already supported by Splunk UBA.

Procedure and requirements for creating custom attributes for HR data

To create custom attributes for HR data, perform the following tasks:

1. From the command line, SSH to the management server as caspida.
2. Perform one or both of the following tasks:
   • Copy the /opt/caspida/conf/attribution/User.json file to the /etc/caspida/local/conf/attribution directory. Modify this file to add user-related attributes.
   • Copy the /opt/caspida/conf/attribution/Account.json file to the /etc/caspida/local/conf/attribution directory. Modify this file to add account-related attributes.
3. Add your desired custom attributes to either User.json or Account.json as desired. See Custom attribute schema for information about the schema.
4. Use a JSON validator to make sure there are no errors in your JSON syntax. You can use any online JSON validator, or use the following command:

   python -m json.tool <filename>.json

   This command can be run from the directory where the JSON file is located. If there are no errors, the full contents of the JSON file are displayed. If there are errors, a message appears with the line number in the file where the error is located.
5. Stop your HR data sources.
6. Run the /opt/caspida/bin/utils/customize_attribution.sh -u command to update the HR data tables in the system. All existing HR data is removed.
7. Synchronize the cluster and restart the Splunk UBA web interface. Do this before re-importing your HR data so that the new attributes are visible in Splunk UBA.
8. Re-import your HR data. You must update the SPL you use to obtain HR data from Splunk Enterprise so that the new HR data attributes are included. After your HR data is available again, you can view your custom attributes in Splunk UBA.

Custom attribute schema

Use this schema to define a new HR data attribute in /etc/caspida/local/conf/attribution/User.json or /etc/caspida/local/conf/attribution/Account.json:

{
  "name": <newAttribute>,
  "sourceNames": [<sourceNameOfAttribute>],
  "properties": {
    "type": <dataTypeOfAttribute>,
    "label": <LabelToBeDisplayedOnUI>,
    "showInDetails": true,  // Set to true, if we want to see it in User page
    "showInGroupBy": true,  // Set to true, if we want to include this attribute to UI group-by 
    "showInFilters": true   // Set to true, if we want to include this attribute in UI filters
  }
}

The fields in the schema are described in this table:

Field	Description
name	The name of the attribute in Splunk UBA.
sourceNames	The name of the fields in your HR data containing the desired value for the Splunk UBA name. Use a comma to separate multiple field names.
type	The data type, such as STRING or BOOLEAN.
label	The name of the attribute as you want it to appear in the Splunk UBA, such as on the HR Data details page.
showInDetails	Set to true if you want this attribute to appear on the User Details page.
showInGroupBy	Set to true if you want this attribute to appear as a grouping attribute when creating a new widget. For example: In Splunk UBA, select Analytics > Custom Dashboards. Click New Widget or select Actions > New Widget. Enter a widget name and select Users Count. Click Next. The custom attribute will appear on the Widget Grouping page.
showInFilters	Set to true if you want this attribute to appear in the filters on the user pages. For example: In Splunk UBA, select Manage > Users to view the users table. Click Add Filter to view all user attributes.

Example: Add a new HR data attribute

In this example, we will walk through how to do the following:

1. Create a new HR data attribute
2. Verify the attribute in Splunk UBA
3. Use the new attribute to create an anomaly action rule

Create a new attribute called Full Time

Suppose we want to create a new attribute called Full Time to designate full-time employees. This is not a field tracked by default in Splunk UBA. Since it is a user-related property, we will add it to Users.json.

1. Log in to the management server as the caspida user.
2. Navigate to the /etc/caspida/local/conf/attribution directory. If this directory does not already exist, create it. For example:

   cd /etc/caspida/local/conf
   mkdir attribution
   cd attribution
   

3. Create a copy of the /opt/caspida/conf/attribution/User.json file in the /etc/caspida/local/conf/attribution directory.

   cp /opt/caspida/conf/attribution/User.json .

4. Edit the User.json file and add the following schema to the file:

   {
       "name": "fulltime",
       "sourceNames": ["fulltime"],
       "properties": {
           "type": "BOOLEAN",
           "label": "Full Time",
           "showInDetails": true,
           "showInGroupBy": true,
           "showInFilters": true
      }
   }
   

5. Save and exit the file.
6. Use a JSON validator to make sure there are no errors in your JSON syntax.

   python -m json.tool User.json

   If you see the full content of the file, then no syntax errors are found.
7. In Splunk UBA, go to Manage > Data Sources and stop any HR data sources that are currently running.
8. Run the following command to update the user attributes in your HR data:

   /opt/caspida/bin/utils/customize_attribution.sh -u

   This command reformats your HR data database tables to add the new attribute and removes all HR data from your system.
9. In distributed deployments, synchronize the cluster.

   /opt/caspida/bin/Caspida sync-cluster  /etc/caspida/local/conf

10. Restart the Splunk UBA web interface:

    sudo service caspida-ui restart

11. Re-import your HR data. You must update the SPL you use to obtain HR data from Splunk Enterprise so that the new HR data attributes are included. See Get HR data into Splunk UBA.

Verify the new Full Time attribute

Check in Splunk UBA to verify that the new Full Time attribute was added.

1. In Splunk UBA, select Manage > HR Data.
2. On the HR Users page, select a user.

Verify that the attribute appears at the top of the page with the other HR data attributes.

Create an anomaly action rule using the Full Time attribute

Follow the instructions in Create an anomaly action rule in Splunk UBA to create a new anomaly action rule using this new user property. You can create an anomaly filter to identity users with this new Full Time attribute and add them to a watchlist, change the anomaly score, or delete anomalies associated with these users.