Context tables

A context table is a container for a data array that is used by KUMA correlators for analyzing events in accordance with correlation rules. You can create context tables in the Resources section. The context table data is stored only in the correlator to which it was added using filters or actions in correlation rules.

You can populate context tables automatically using correlation rules of 'simple' and 'operational' types or import a file with data for the context table.

You can add, copy, and delete context tables, as well as edit their settings.

Context tables can be used in the following KUMA services and features:

• Correlation rules.
• Dashboard.

The same context table can be used in multiple correlators. However, a separate entity of the context table is created for each correlator. Therefore, the contents of the context tables used by different correlators are different even if the context tables have the same name and ID.

Only data based on correlation rules of the correlator are added to the context table.

You can add, edit, delete, import, and export records in the context table of the correlator.

During the correlation process, when entries are deleted from context tables, service events are generated in the correlators. These events only exist in the correlators, and they are not redirected to other destinations. Service events are sent for processing by correlation rules of that correlator which uses the context table. Correlation rules can be configured to track these events so that they can be used to identify threats.

Service event fields for deleting an entry from a context table are described below.

Viewing the list of context tables

To view the context table list of the correlator:

1. In the KUMA console, select the Resources section.
2. In the Services section, click the Active services button.
3. In the context menu of the correlator for which you want to view context tables, select Go to context tables.

The Correlator context tables list is displayed.

The table contains the following data:

• Name—name of the context table.
• Size on disk—size of the context table.
• Directory—path to the context table on the KUMA correlator server.

Adding a context table

To add a context table:

1. In the KUMA console, select the Resources section.
2. In the Resources section, click Context tables.
3. In the Context tables window, click Add.

   This opens the Create context table window.

4. In the Name field, enter a name for the context table.
5. In the Tenant drop-down list, select the tenant that owns the resource.
6. In the TTL field, specify time the record added to the context table is stored in it.

   When the specified time expires, the record is deleted. The time is specified in seconds. The maximum value is 31536000 (1 year).

   The default value is 0. If the value of the field is 0, the record is stored indefinitely.

7. In the Description field, provide any additional information.

   You can use up to 4,000 Unicode characters.

   This field is optional.

8. In the Schema section, specify which fields the context table has and the data types of the fields.

   Depending on the data type, a field may or may not be a key field. At least one field in the table must be a key field. The names of all fields must be unique.

   To add a table row, click Add and fill in the table fields:

   1. In the Name field, enter the name of the field. The maximum length is 128 characters.
   2. In the Type drop-down list, select the data type for the field.

      Possible field data types

      Possible data types of context table fields

      Field data type	Can be a key field	Comment
      Integer	Yes
      Floating point number	Yes
      String	Yes
      Boolean	Yes
      Timestamp	Yes	For a field of this type, it is checked that the field value is greater than or equal to zero. No other operations are provided.
      IP address	Yes	For a field of this type, it is checked that the field value corresponds to the IPv4, IPv6 format. No other operations are provided.
      Integer list	No
      Float list	No
      List of strings	No
      Boolean list	No
      Timestamp list	No	For a field of this type, it is checked that each item in the list is greater than or equal to zero. No other operations are provided.
      IP list	No	For a field of this type, it is checked that each item of the list corresponds to the IPv4, IPv6 format. No other operations are provided.

   3. If you want to make a field a key field, select the Key field check box.

      A table can have multiple key fields. Key fields are chosen when the context table is created, uniquely identify a table entry and cannot be changed.

      If a context table has multiple key fields, each table entry is uniquely identified by multiple fields (composite key).

9. Add the required number of context table rows.

   After saving the context table, the schema cannot be changed.

10. Click the Save button.

The context table is added.

Viewing context table settings

To view the context table settings:

1. In the KUMA web interface, select the Resources section.
2. In the Resources section, click Context tables.
3. In the list in the Context tables window, select the context table whose settings you want to view.

This opens the context table settings window. It displays the following information:

• Name—unique name of the resource.
• Tenant—the name of the tenant that owns the resource.
• TTL—the record added to the context table is stored in it for this duration. This value is specified in seconds.
• Description—any additional information about the resource.
• Schema is an ordered list of fields and their data types, with key fields marked.

Editing context table settings

To edit context table settings:

1. In the KUMA web interface, select the Resources section.
2. In the Resources section, click Context tables.
3. In the list in the Context tables window, select the context table whose settings you want to edit.
4. Specify the values of the following parameters:
   • Name—unique name of the resource.
   • TTL—the record added to the context table is stored in it for this duration. This value is specified in seconds.
   • Description—any additional information about the resource.
   • Schema is an ordered list of fields and their data types, with key fields marked. If the context table is not used in a correlation rule, you can edit the list of fields.

     If you want to edit the schema in a context table that is already being used in a correlation rule, follow the steps below.

   The Tenant field is not available for editing.

5. Click Save.

To edit the settings of the context table previously used by the correlator:

1. Export data from the table.
2. Copy and save the path to the file with the data of the table on the disk of the correlator. This path is specified in the Directory column in the Correlator context tables window. You will need this path later to delete the file from the disk of the correlator.
3. Delete the context table from the correlator.
4. Edit context table settings as necessary.
5. Delete the file with data of the table on the disk of the correlator at the path from step 2.
6. Add the context table in which you edited the settings to the correlator.
7. To restart the correlator, in the Resources → Active services section, in the list of services, select the check box next to the relevant correlator, click the three-dots icon on the toolbar and in the displayed menu, select Restart.
8. Adapt the fields in the exported table (see step 1) so that they match the fields of the table that you uploaded to the correlator at step 6.
9. Import the adapted data to the context table.

Duplicating context table settings

To copy a context table:

1. In the KUMA web interface, select the Resources section.
2. In the Resources section, click Context tables.
3. Select the check box next to the context table that you want to copy.
4. Click Duplicate.
5. Specify the necessary settings.
6. Click the Save button.

The context table is copied.

Deleting a context table

You can delete only those context tables that are not used in any of the correlators.

To delete a context table:

1. In the KUMA console, select the Resources section.
2. In the Resources section, click Context tables.
3. Select the check boxes next to the context tables that you want to delete.

   To delete all context tables, select the check box next to the Name column.

   At least one check box must be selected.

4. Click the Delete button.
5. Click OK.

The context tables are deleted.

Viewing context table records

To view a list of context table records:

1. In the KUMA web interface, select the Resources section.
2. In the Services section, click the Active services button.
3. In the context menu of the correlator for which you want to view the context table, select Go to context tables.

   This opens the Correlator context tables window.

4. In the Name column, select the relevant context table.

The list of records for the selected context table is displayed.

The list contains the following data:

• Key is the composite key of the record. It is comprised by one or more values of key fields, separated by the "|" character. If one of the key field values is absent, the separator character is still displayed.

  For example, a record key consists of three fields: DestinationAddress, DestinationPort, and SourceUserName. If the last two fields do not contain values, the record key is displayed as follows: 43.65.76.98| | .

• Record repetitions is the total number of times the record was mentioned in events and identical records were downloaded when importing context tables to KUMA.
• Expiration date – date and time when the record must be deleted.

  If the TTL field had the value of 0 when the context table was created, the records of this context table are retained for 36,000 days (approximately 100 years).

• Updated is the date and time when the context table was updated.

Searching context table records

To find a record in the context table:

1. In the KUMA web interface, select the Resources section.
2. In the Services section, click the Active services button.
3. In the context menu of the correlator in whose context table you want to find a record, select Go to context tables.

   This opens the Correlator context tables window.

4. In the Name column, select your context table.

   This opens a window with the records of the selected context table.

5. In the Search field, enter the record key value or several characters from the key.

The list of context table records displays only the records whose key contains the entered characters.

If the your search query matches records with empty key values, the text <Nothing found> is displayed in the widget on the Dashboard. We recommend clarifying the conditions of your search query.

Adding a context table record

To add a record to the context table:

1. In the KUMA web interface, select the Resources section.
2. In the Services section, click the Active services button.
3. In the context menu of the correlator to whose context table you want to add a record, select Go to context tables.

   This opens the Correlator context tables window.

4. In the Name column, select the relevant context table.

   The list of records for the selected context table is displayed.

5. Click Add.

   The Create record window opens.

6. In the Value field, specify the values for fields in the Field column.

   KUMA takes field names from the correlation rules with which the context table is associated. These names are not editable. The list of fields cannot be edited.

   If you do not specify some of the field values, the missing fields, including key fields, are populated with default values. The key of the record is determined from the full set of fields, and the record is added to the table. If an identical key already exists in the table, an error is displayed.

   List of default field values

   Field type	Default value
   Integer	0
   Floating point number	0.0
   String	""
   Boolean	false
   IP address	"0.0.0.0"
   Timestamp	0
   Integer list	[]
   Float list	[]
   List of strings	[]
   Boolean list	[]
   Timestamp list	[]
   IP list	[]

7. Click the Save button.

The record is added.

Editing a context table record

To edit a record in the context table:

1. In the KUMA web interface, select the Resources section.
2. In the Services section, click the Active services button.
3. In the context menu of the correlator for which you want to edit the context table, select Go to context tables.

   This opens the Correlator context tables window.

4. In the Name column, select the relevant context table.

   The list of records for the selected context table is displayed.

5. Click on the row of the record that you want to edit.
6. Specify your values in the Value column.
7. Click the Save button.

The record is overwritten.

Restrictions when editing a record:

• The value of the key field of the record is not available for editing. You can change it by exporting and importing a record.
• Field names in the Field column are not editable.
• The values in the Value column must meet the following requirements:
  • greater than or equal to 0 for fields of the Timestamp and Timestamp list types.
  • IPv4 or IPv6 format for fields of the IP address and IP list types.
  • is true or false for a Boolean field.

Deleting a context table record

To delete records from a context table:

1. In the KUMA web interface, select the Resources section.
2. In the Services section, click the Active services button.
3. In the context menu of the correlator from whose context table you want to delete a record, select Go to context tables.

   This opens the Correlator context tables window.

4. In the Name column, select the relevant context table.

   The list of records for the selected context table is displayed.

5. Select the check boxes next to the records you want to delete.

   To delete all records, select the check box next to the Key column.

   At least one check box must be selected.

6. Click the Delete button.
7. Click OK.

The records will be deleted.

Importing data into a context table

To import data to a context table:

1. In the KUMA web interface, select the Resources section.
2. In the Services section, click the Active services button.
3. In the context menu of the correlator to whose context table you want to import data, select Go to context tables.

   This opens the Correlator context tables window.

4. Select the check box next to your context table and click Import.

   This opens the context table data import window.

5. Click Add and select the file that you want to import.
6. In the Format drop-down list select the format of the file:
   • csv
   • tsv
   • internal
7. Click the Import button.

The data from the file is imported into the context table. Records that previously existed in the context table are preserved.

When importing, KUMA checks the uniqueness of each record's key. If a record already exists, its fields are populated with new values obtained by merging the previous values with the field values of the imported record.

If no record existed in the context table, a new record is created.

Data imported from a file is not checked for invalid characters. If you use this data in widgets, widgets are displayed incorrectly if invalid characters are present in the data.