Appendix

This section provides information that supplements the main text of the document.

Settings of a .env configuration file

The settings of the configuration file can be changed only by a qualified technical specialist of the Customer, a Kaspersky employee, or a certified integrator.

The .env configuration file is filled in to configure the CEF Connector and has the settings described in the table below.

Settings of a .env configuration file

To apply changes to the configuration file, restart Kaspersky MLAD.

Settings and example of the Excel file containing tag and asset configuration

The configuration file is created by a qualified technical specialist of the Customer, a Kaspersky employee or a certified integrator. The system administrator loads the configuration of assets and tags of a hierarchical structure in the Assets section in the administrator menu.

The configuration file contains the following tabs:

• readme: A tab containing general information about the configuration file.
• directory_types: A tab that describes the hierarchical structure asset types using the following settings:
  • directory_type_id: The asset type ID. The ID is assigned automatically when exporting the asset tree.
  • directory_type: A unique name for the asset type.
  • parameter<parameter number>_label: Names of special parameters, where <parameter number> corresponds to a value in the range from 1 to 5. If an asset of a given type does not have any special parameter, leave the corresponding field in the configuration file blank.
  • description: The description of the asset type. This field is optional.
• directories: A tab that describes assets of the hierarchical structure using the following settings:
  • directory_id: The asset ID. The ID is assigned automatically when exporting the asset tree.
  • directory_type: The type of asset. The type is selected from the asset types specified on the directory_types tab.
  • directory_type row: The number of the row on the directory_types tab that describes the selected asset type. The field is filled in automatically.
  • directory_name: The unique name of an asset within its parent asset.
  • directory_info: The description of the asset. This field is optional.
  • parent: The parent asset. If the imported asset is at the top level of the asset hierarchy, leave the parent field blank.
  • parent row: The number of the row on which the selected parent asset is described. The field is filled in automatically.
  • parent_id: The ID of the parent asset. The ID is assigned automatically when exporting the asset tree.
  • parameter<parameter number>: Names of special parameters, where <parameter number> corresponds to a value in the range from 1 to 5. Names of special parameters are filled in automatically if special parameters are defined for the selected asset type.
  • value <parameter number>: Values of special parameters, where <parameter number> corresponds to a value in the range from 1 to 5. If an asset does not have a special parameter, leave the field for entering the corresponding value blank.
• tags: A tab that describes tags of the hierarchical structure using the following parameters:
  • tag_id refers to the tag ID. An ID value is assigned automatically in the range of 1 to 1,000,000 when exporting primary members of the hierarchical structure.
  • tag_name is the unique name of the tag.
  • alternate_name: A unique alternative name for the tag. This field is optional.
  • tag_description refers to a description of the tag.
  • parent: The parent asset to which the tag belongs. If the head element of the hierarchical structure is the tag imported by the parent element, leave the parent field blank.
  • parent_row: The number of the row on the directories tab that describes the selected parent asset. The field is filled in automatically.
  • parent_id: The ID of the parent asset. The ID is assigned automatically when exporting the asset tree.
  • tag_type: Type of tag. This field is optional.
    • PV: To designate measurements or observed values of physical parameters.
    • CV: To designate calculated values of physical parameters.
    • IV: To designate tags that are independent of other tags.
    • SV: To designate a setpoint.
    • MV: To designate the controlled values of physical parameters.
    • B: To designate tags in bit format.
    • X: To designate cases that are not tagged.

    If you are finding it difficult to determine the tag type, you can use a question mark (?) as the tag type instead.

  • tag_units: The unit of measure for the tag.
  • red_min: The lower threshold for the maximum permissible tag value. This field is optional.
  • red_max: The upper threshold for the maximum permissible tag value. This field is optional.
  • yellow_min: Lower signaling threshold, upon reaching which the operator should pay attention to the tag behavior. This field is optional.
  • yellow_max: Upper signaling threshold, upon reaching which the operator should pay attention to the tag behavior. This field is optional.
  • validity_min: The lower threshold for physically possible tag values. This field is optional.
  • validity_max: The upper threshold for physically possible tag values. This field is optional.
  • display_min: The lower boundary for displaying tag values on graphs. This field is optional.
  • display_max: The upper boundary for displaying tag values on graphs. This field is optional.
  • scale: The expression used to calculate the tag value from the value passed to Kaspersky MLAD. Instead of an expression, you can specify a specific number by which the value of the transmitted tag is to be multiplied. If the tag value does not need to be recalculated, leave this field blank.
  • comment: A comment relating to the tag.
  • X is the coordinate of the monitored asset's sensor location. This field is optional.
  • Y is the Y coordinate of the monitored asset's sensor location. This field is optional.
  • Z is the Z coordinate of the monitored asset's sensor location. This field is optional.
  • bias is the value to be added to the tag value passed to Kaspersky MLAD. Enter 0 if no value conversion is required.

    Values received in Kaspersky MLAD are converted if the Scale obtained tag values toggle switch is on in the settings of the employed connector. The bias value is added to the result from multiplying the resulting tag value by the multiplier value.

  • multiplier is the multiplier for the tag value passed to Kaspersky MLAD. Enter 1 if no value conversion is required.

    Values received in Kaspersky MLAD are converted if the Scale obtained tag values toggle switch is on in the settings of the employed connector. The resulting tag value is multiplied by the multiplier value before adding the bias value.

Below is an example of a XLSX file containing descriptions of assets and tags and their configuration.

Directory_types tab

Directories tab

tags tab

Settings and an example of JSON file that describes presets

JSON file that describes presets is created by a qualified technical specialist of the Customer, a Kaspersky employee or a certified integrator. The file that describes presets is uploaded by the user in the Presets section.

JSON file defines information about presets under presets, which itself contains the following settings:

• name: preset name.

• Code is the preset ID in the Kaspersky MLAD database. An ID is assigned automatically when the file is uploaded.
• Sort is a sequential display number of the preset under Presets.
• tags: a list of IDs for the tags included in the preset
• icon: preset icon name
• css_class: the name of the CSS class for preset icon display
• is_display_on_time_slice determines whether the preset should be displayed under Time slice. If this is set to true, the preset is displayed under Time slice.
• evaluations: describes the graph in the Time slice section by using the following settings:
  • axis_x_name: x-axis label.
  • evaluations: describes the expression used to calculate tag values for graph display by using the following:
    • name: the name of the expression used to calculate tag values for graph display.
    • yAxis: y-axis label.
    • expression is an expression used to calculate the tag values
    • expression_color: preset graph color. Chart color is set with the help of RGB codes by using the following settings:
      • a: alpha opacity setting You can specify a value in the range of 0 to 1.
      • b: blue channel coordinate You can specify a value in the range of 0 to 255.
      • g: green channel coordinate You can specify a value in the range of 0 to 255.
      • r: red channel coordinate You can specify a value in the range of 0 to 255.
• Graphic_areas is a group of settings that describe the graphic areas within the preset.
  • Name is the name of the graphic area.
  • Description is the description of the graphic area.
  • Sort is a sequential display number of the graphic area in the preset under Presets, History, and Monitoring.
  • Display_max is an upper limit for displaying tags associated with the graphic area. If is_scale_mode_auto is true, set display_max to null.
  • Display_min is a lower boundary for displaying tags associated with the graphics area. If is_scale_mode_auto is true, set display_min to null.
  • Additional_thresholds is a group of settings that describe additional threshold lines.
    • Id is the ID of the additional threshold line. An ID is assigned automatically when the file is uploaded.
    • value: threshold value.
    • Color is a color of the graph that will be displayed for the additional threshold line. Chart color is set with the help of RGB codes by using the following settings:
      • a: alpha opacity setting You can specify a value in the range of 0 to 1.
      • r: red channel coordinate You can specify a value in the range of 0 to 255.
      • g: green channel coordinate You can specify a value in the range of 0 to 255.
      • b: blue channel coordinate You can specify a value in the range of 0 to 255.
  • Scale_mode is the axis scaling mode. You can specify one of the following values for the scale_mode setting:
    • single_axis: uses one Y-axis to display tag data on the graph.
    • cast: scales data along the Y-axis for each tag individually, irrespective of data from other tags in the graphic area.
  • Is_scale_mode_auto is a setting that defines the method of graph scaling in single axis mode. When this is set to true, the tag graph is automatically scaled based on the minimum and maximum data values of all tags in the graphic area.
  • tag_id_list: a list of tag IDs that are included in the graphic area.
  • Graphic_area_id is the ID of the graphic area. An ID is assigned automatically when the file is uploaded.
  • Preset_id is the ID of the preset the graphic area belongs to. An ID is assigned automatically when the file is uploaded.

Below is an example of a JSON file containing descriptions of presets.

Settings and an example of JSON file containing a configuration for the Event Processor service

The configuration file is created by a technical specialist of the Customer, a Kaspersky employee, or a certified integrator. The system administrator uploads the Event Processor configuration file when configuring the Event Processor service settings.

When re-uploading a configuration file in which other event parameters are defined, the event parameters defined in the previous configuration file will become unavailable for configuration in the application web interface.

The CEF Connector receives information about each detected event from external systems in CEF format:

where:

• CEF:<CEF format version>|<name of the external system vendor>|<name of the external system application>|<version of the external system application>|<unique identifier of the event type>|<event description>|<event severity level>| is the event header.
• <parameter 1>=<value of parameter 1> ... <parameter N>=<value of parameter N> is the event body containing the sequence of <event parameter>=<event parameter value> pairs.

The configuration file describes the parameters in the events received by the CEF Connector. The names of event parameters in Kaspersky MLAD may coincide with the names of parameters received in CEF format by the CEF Connector. If necessary, you can specify other names for the parameters to be processed in Kaspersky MLAD according to certain rules. The rules for mapping event parameters are defined in the mapping_fields parameter of the configuration file.

The nodes and links parameters of the configuration file are intended to describe the method for constructing the event search results graph. The graph displays the relationships between event parameters whose nodes are defined in the nodes parameter and whose arcs are defined in the links parameter.

The configuration file contains the following settings:

• timestamp_field: the name of the setting for indicating the date and time in events that CEF Connector receives from an external system.
• timestamp_scale: the unit of time for events.
• sep: separator between the parameters of values in events received by the CEF Connector.
• sep_kv: separator between the key and value in events received by the CEF Connector.
• sep_cef_caption: separator in the header of events received by the CEF Connector.
• mapping_fields: rules for mapping event parameters received by the CEF Connector to the names of event parameters to be processed in Kaspersky MLAD. If necessary, you can specify the conditions for writing event parameters in Kaspersky MLAD depending on the values of other parameters received by the CEF Connector. This parameter is optional.
• fields: list of event parameters processed by the Event Processor service. The names of these parameters may coincide with the names of parameters received in CEF format, or may coincide with the names of parameters defined in the rules using the mapping_fields parameter.
• nodes: the group of settings that describe event parameters relationship graph nodes by using the following settings:
  • name: the name of the event parameter corresponding to the graph node.
  • depth: the order (left to right) of displaying the graph node in event history.
  • tooltip: enables templates. templates: defines the tooltip displayed when you hover over the node.
  • fieldShortCut: defines an alternate name for the event parameter. The event parameters relationship graph displays the alternate name in brackets next to the value of the parameter corresponding to the graph node. This parameter is optional.
• links: a group of settings that describe graph arcs (event parameters relationships) by using the following settings:
  • source: the name of the first event parameter that creates a link on the graph.
  • target: the name of the second event parameter that creates a link on the graph.
  • tooltip: enables templates. The templates setting defines the tooltip displayed when you hover over the node. You can use the following variables with double curly braces:
    • Any parameter in the fields event parameter list.
    • onIntervalActivationsCount: the number of event detections in the event stream during the period defined when viewing the events history.
    • onIntervalLastActivationTimestamp: the date and time when the event was last detected in the event stream for the period defined when viewing the events history.
    • lastActivationTimestamp: the date and time when the event was last detected in the event stream.
    • totalActivationsCount: the number of event detections in the event stream.
  • isGraphGroup: defines how to display a connection on the event parameters relationship graph. If this parameter is set to true, events with different values of the parameters that are not used as the graph nodes are displayed as one event group. If the parameter is set to false, events with different values of the parameters are displayed as different events. The default value of this parameter is false.

Below is an example of a JSON file containing a configuration for the Event Processor service. The file contains a description of the event parameters for the Event Processor. According to the values specified in the mapping_fields parameter, events with the following event parameters will be displayed in Kaspersky MLAD:

• EventType: corresponds to the cat parameter in an event received by the CEF Connector.
• User_Name: corresponds to the cs1 parameter if the value user is received for the cs1Label parameter.
• Destination_Host: corresponds to the cs1 parameter if the value destination is received for the cs1Label parameter.
• Access_Result: corresponds to the cs1 parameter if the value access is received for the cs1Label parameter.

  { "timestamp_field": "TimeStamp", "timestamp_scale": "ms", "sep": " ", "sep_kv": "=", "sep_cef_caption": "|", "mapping_fields": { "cat": "User_Host", "cs1": {"map_label": "cs1Label", "values": {"user": "User_Name", "destination": "Destination_Host", "access": "Access_Result"}} }, "fields": [ "User_Host", "User_Name", "Destination_Host", "Access_Result" ], "nodes": [ { "name": "User_Name", "depth": 0, "tooltip": { "templates": [ "User: {{User_Name}}" ] }, "fieldShortCut": "User" }, { "name": "User_Host", "depth": 1, "tooltip": { "templates": [ "User host: {{User_Host}}" ] }, "fieldShortCut": "Src" }, { "name": "Destination_Host", "depth": 2, "tooltip": { "templates": [ "Destination: {{Destination_Host}}" ] }, "fieldShortCut": "Dst" } ], "links": [ { "source": "User_Name", "target": "User_Host", "tooltip": { "templates": [ "{{User_Name}} » {{User_Host}}", "Count: {{onIntervalActivationsCount}}" ] }, "isGraphGroup": true }, { "source": "User_Host", "target": "Destination_Host", "tooltip": { "templates": [ "{{User_Host}} » {{Destination_Host}}", "DeviceEventClassID: {{Access_Result}}", "Count: {{onIntervalActivationsCount}}" ] } } ] }

Viewing the Kaspersky MLAD log

Kaspersky MLAD uses the Grafana logging system to monitor the state of application services and to track information security events.

Tracking information security events of Kaspersky MLAD in the logging subsystem

The table below shows the types of information security events that are tracked in Kaspersky MLAD.

Types of information security events

Each entry about an information security event contains the following parameters:

• event_id is the ID of the information security event.
• timestamp is the date and time of the information security event.
• event_type is the ID of the information security event type.
• sub_type specifies the type of information security event.
• severity is the importance of the information security event. Kaspersky MLAD provides the following severity levels for information security events:
  • 1 (low).

    These information security events include entries involving users being granted access to perform a specific action in the web interface, and regarding the successful completion of any user actions.

  • 5 (medium).

    These information security events include entries involving user actions in the web interface for managing ML models, tags, user accounts and passwords, and entries regarding exceeded thresholds for storage time and volume of information security event logs.

  • 8 (high).

    These information security events include entries involving users entering an incorrect user name and/or password when connecting to the web interface of the application, and entries regarding unsuccessful attempts to change a password.

  • 10 (highest).

    These information security events include entries involving attempts to connect to the application web interface using a system account or a blocked account, and entries regarding attempts to perform specific actions in the application without the appropriate access rights.

• username is the name of the user whose actions resulted in the information security event entry.
• ip_address is the IP address of the computer from which the user performed the action logged into the information security event log.
• outcome is the result of an information security event. The OK result corresponds to successful completion of the operation by the user. The FAIL result corresponds to failure of the user to perform the operation.
• msg is a brief summary of the information security event.
• info is a detailed description of the information security event.

Tracking the state of Kaspersky MLAD services in the logging subsystem

Kaspersky MLAD services whose states are monitored in the logging subsystem are identified based on the names of their corresponding containers or images in Docker. In most cases, the abbreviated name of the service is used as the name of the image. The container name is formed according to the following template:

<application directory>-<image name>-#,

where # is the number of the Docker container.

By default, Kaspersky MLAD uses the mlad-release-5.0.0-<installation build number> directory.

The Kaspersky MLAD log stores entries about the state of application services only for the last 48 hours.

The table below presents the correspondence between Kaspersky MLAD services and the names of Docker containers and images.

Correspondence between Kaspersky MLAD services and the names of Docker containers and images

The Info logging level is used for the Time Series Database, Message Broker, Logger, Database and Web Server services, and for webstatic image. The logging levels for all other Kaspersky MLAD services are defined by the system administrator when configuring the application settings.

Scenario: viewing information security event logs

Before starting to work with the logging subsystem, it is recommended to read the Grafana User Guide.

The maximum volume and storage time for information security event entries are defined when configuring the security settings.

Information security event logs are written to the Kaspersky MLAD database automatically. If necessary, the system administrator can specify the settings of an external system to which the information security event logs should be sent.

The scenario for viewing information security event logs consists of the following steps:

1. Navigating to the logging subsystem

   Go to the logging system by clicking the button. This opens the Grafana interface in which you need to enter the name and password of the Kaspersky MLAD user.

   Available only to the system administrators and users with the Manage application logs permission.

2. Navigating to the section containing information security event logs

   Go to the Security audit section.

3. Analyzing information security event logs

   Analyze the information security event log entries for the selected period. You can filter them based on parameters of the information security event logs. To do so, click the button in the column containing the relevant log parameter, select the check boxes next to the necessary filtering criteria, and click OK. To reset the filtering criteria, clear the relevant check boxes and click OK.

4. Exporting information security event logs

   To export the information security event logs for the selected period to a text file, under Security audit, choose Inspect → Data from the vertical menu in the upper right corner of the information security event log table, and in the panel that opens, click Download CSV.

Scenario: assessing the main metrics of Kaspersky MLAD

Before starting to work with the logging subsystem, it is recommended to read the Grafana User Guide.

When connecting to the logging subsystem for the first time, you must change the default password.

This subsection provides a sequence of actions that must be performed to assess the health and general state of Kaspersky MLAD.

The scenario for assessing the health and general state of Kaspersky MLAD consists of the following steps:

1. Navigating to the logging subsystem

   Go to the logging system by clicking the button. This opens the Grafana interface in which you need to enter the name and password of the Kaspersky MLAD user.

   Available only to the system administrators and users with the Manage application logs permission.

2. Analyzing the main metrics of Kaspersky MLAD

   In the Summary docker metrics section, analyze the graphs of the main Kaspersky MLAD metrics for the selected period.

   The following metrics are displayed for each container of Kaspersky MLAD services:

   • CPU usage – history of central processor workload caused by the container. This is measured as a percentage.
   • RAM usage – history of the container's RAM usage. This is measured in bytes.
   • Disk usage Read/Write – history of the container's load on the disk subsystem (read/write operations). This is measured in bytes.
   • Network usage – history of the container's use of network resources. This is measured in bytes per second.

Scenario: viewing container logs and metrics

Before starting to work with the logging subsystem, it is recommended to read the Grafana User Guide.

The Kaspersky MLAD log stores entries only for the last 48 hours.

This subsection provides steps for assessing the performance and viewing the logs of a specific container from the Kaspersky MLAD distribution kit.

The scenario for assessing the performance and viewing the logs of a specific container consists of the following steps:

1. Navigating to the logging subsystem

   Go to the logging system by clicking the button. This opens the Grafana interface in which you need to enter the name and password of the Kaspersky MLAD user.

   Available only to the system administrators and users with the Manage application logs permission.

2. Navigating to the section with container logs and metrics

   Go to the Service detailed monitoring section and select the relevant container from the Container drop-down list.

3. Analyzing container metrics

   In the Service detailed monitoring section, analyze the graphs of Kaspersky MLAD metrics for the selected container during the relevant period.

   The Service detailed monitoring section provides the following metrics:

   • Memory – history of the container's RAM usage. This is measured in bytes.
   • CPU – history of central processor workload caused by the container. This is measured as a percentage.
   • File system – history of the container's load on the disk subsystem (read/write operations). This is measured in bytes.
   • Network – history of the container's use of network resources. This is measured in bytes per second.
4. Analyzing container metrics

   Analyze the container log records for the selected period, which are displayed under the metrics dashboard. You can search the container log records. To do so, enter a search query in the Log search field and press the ENTER key. To reset the search results, clear the Log search field and press the ENTER key.

5. Exporting container logs

   To export container logs for the selected period to a text file, under Service detailed monitoring, choose Inspect → Data from the vertical menu in the upper right corner of the relevant metric section, and in the panel that opens, click Download CSV.

Special characters of regular expressions

You can use regular expressions to search for events, patterns and values of event parameters in the Event Processor section. Kaspersky MLAD supports use of the following special characters in regular expressions:

• ^ – Corresponds to the start of the parameter value. For example, ^A means that the event parameter search will look for values beginning with the letter A.
• $ – Corresponds to the end of the parameter value. For example, A$ means that the event parameter search will look for values ending with the letter A.
• . – Corresponds to any single character.
• | – Splits permissible options for characters or a set of characters in a parameter value. For example, c(o|a)t matches both the cot and cat values.
• \ – Indicates that the next character is an ordinary character (not a special character) in the parameter value. You can use the \ character to search for special characters in a parameter value. For example, \. describes a dot in the parameter value, while \\ describes a backslash.
• [] – Corresponds to any character from the set of permissible characters. For example, [abc] matches the occurrence of any one of the three specified characters.

  To search for a range of values, you can use the - character. To find the characters that are not within the specified range, you can use the ^ character in the square brackets. For example, [^0-9] means any character except numerals can be present.

You can use the following special characters to indicate the necessary number of repetitions of an expression in the values of event parameters:

• ? – Character indicating that the preceding expression may occur zero or one time in a parameter value.
• * – Character indicating that the preceding expression may occur zero or more times in a parameter value.
• + – Character indicating that the preceding expression may occur one or more times in a parameter value.
• {} – Character class that lets you indicate the necessary number of repetitions of the preceding expression. You can specify the repetition count in one of the following ways:
  • {n} – The expression preceding the curly brackets occurs in the parameter value exactly n times.
  • {m,n} – The expression preceding the curly brackets occurs in the parameter value from m to n times inclusive.
  • {m,} – The expression preceding the curly brackets occurs in the parameter value at least m times.
  • {,n} – The expression preceding the curly brackets occurs in the parameter value no more than n times.

You can also use parentheses () to group elements of an expression. For example, (c[oa]t){2} matches cotcot, catcat, cotcat, and catcot.

Cipher suites for secure TLS connection

It is recommended to use the following cipher suite for a secure TLS connection via the TLS-1.2 protocol:

• TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384;
• TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256;
• TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256;
• TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384;
• TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256;
• TLS_DHE_RSA_WITH_CHACHA20_POLY1305_SHA256;
• TLS_DHE_RSA_WITH_AES_256_GCM_SHA384.

It is recommended to use the following cipher suite for a secure TLS connection via the TLS-1.3 protocol:

• TLS_AES_128_GCM_SHA256;
• TLS_AES_256_GCM_SHA384;
• TLS_CHACHA20_POLY1305_SHA256;
• TLS_AES_128_CCM_SHA256.