Kaspersky Industrial CyberSecurity for Networks API Developer's Guide

Using filters for events

This section describes filters and filter syntax, and provides filter examples for events.

About filters for events

Filters are strings that can be specified in RPC calls. A filter is a group of conditions and logical operators that places constraints on the returned data.

For example, if you want to get the events by using the GetItemsById method of EventProviderService, and you also want only those events that are of a critical severity, then you can use the following filter:

filter: {

severity = critical

}

For examples of using filters, see subsection "Making event requests with filters" below.

You can combine conditions using logical operators and use special nested filters (property bags) for compound fields:

filter: {

(severity = critical && technology = dpi) ||

(monitoring_point = mp1, mp2 &&

src_address = {

ip : linklocal &&

port : 8080

})

}

About conditions

Filters can have two types of conditions:

  • Basic conditions

    A basic condition is an expression in a field = value format, where field is the name of the field affected by the condition and value is a constraint.

    For more information about condition syntax, see subsection "Basic condition syntax" below.

    Condition example: event_id = 42.

  • Property bags

    Property bag is a special condition for compound fields. It acts like a nested filter for compound field elements.

    For more information about property bag syntax, see subsection "Property bag syntax" below.

    Condition example: src_address = { ip: internet && vlan_id: 1 }.

About logical operators

Filters support logical operators and parentheses. By using these, you can combine conditions and construct complex constraints for returned data.

The following logical operators are supported:

  • Logical AND operator (&&)
  • Logical OR operator (||)
  • Negation (!)

For example, the following filter causes Kaspersky Industrial CyberSecurity for Networks to return events with critical severity generated by DPI technology and also events with warning and critical severity from certain monitoring points:

filter: {

(severity = critical && technology = dpi) || (!severity = info && monitoring_point = mp1, mp2)

}

Basic condition syntax

Basic condition is an expression that defines constraint for a field.

Basic condition has the following format:

field = value

Above, field is the name of the field affected by the condition, and value is a constraint.

The following are examples of basic conditions:

event_id = 42

technology = dpi

protocol = "Loopback"

Property bag syntax

Property bag is a special condition for compound fields. It acts like a nested filter for compound field elements.

Property bag is an expression in the following format:

field = { subfield : value }

Above, field is the name of the compound field affected by the property bag condition, subfield is a name of the element of the compound field, and value is a constraint for subfield.

Property bags use syntax described in this section, with two important exceptions:

  • Property bag conditions use the field : value syntax instead of the field = value syntax.
  • Logical NOT operator uses the ~ symbol instead of the ! symbol.

The following is a property bag condition example:

src_address = {

(ip: linklocal && ~port: 8080) ||

(ip: internet && vlan_id: 1, 5)

}

Condition value types

Filters support the following value types for conditions:

  • Integral

    An integral value in a range from 0 to the maximum value for this field.

    Condition example: event_id = 55.

  • Date and time

    A date and time specified in ISO-8601 format.

    This value type supports only ranges. For more information about ranges, see subsection "Condition value ranges" below.

    Condition example: occurred = 2017-05-22T11:25:00Z-2017-05-23T11:25:00Z.

  • Enumeration

    A string literal from a list of defined literals for this field.

    Condition example: technology = dpi.

  • String value

    A string literal.

    The string can be enclosed in double quotation marks ("). If the string does not contain the special characters in the following paragraph, it must be enclosed in quotation marks.

    A string containing the following symbols and symbol ranges does not have to be enclosed in quotation marks: 0-9, a-z, A-Z, <>, [], ;, _, ..

    A string cannot contain double quotation marks (").

    Condition example: protocol = "ProfinetEtherType".

  • IPv4 address

    An IPv4 address.

    IPv4 addresses can be specified in one of the following formats:

    • Single address (octets): xxx.xxx.xxx.xxx
    • Range of addresses (octets): xxx.xxx.xxx.xxx-xxx.xxx.xxx.xxx
    • Range of addresses (subnet): xxx.xxx.xxx.xxx/xx

      Subnet IPv4 address format always specifies a range of addresses. For example, the 192.0.2.0/24 value is equivalent to the 192.0.2.0-192.0.2.255 range of addresses.

    • One of the literals in the following enumeration:
      • loopback

        Loopback communication. IP addresses in the 127.0.0.0/8 range.

      • linklocal

        Automatic Private IP Addressing. IP addresses in the 169.254.0.0/16 range.

      • ipv4multicast

        Multicast IP addresses. IP addresses in the 224.0.0.0/4 range.

      • privatenetwork

        Private network IP addresses. IP addresses in the 172.16.0.0/12 range.

      • internet

        Any other IP address.

    Condition example (property bag): src_address = { ip : 192.0.2.40 }.

  • Media access control (MAC) address

    A MAC address in the following format:

    • Six octets: xx:xx:xx:xx:xx:xx

    Condition example (property bag): src_address = { mac: 00:00:5E:00:53:10 }.

Condition value ranges

When specifying values, you can use ranges. A range includes all values in a certain interval.

Ranges use the following syntax:

value_1-value_N

Above, value_1 is the beginning of an interval, value_N is the end of an interval.

Following value types support ranges:

  • Integral
  • Date and time
  • IPv4 address
  • MAC address

The following are examples of ranges:

event_id = 1000-1500

occurred = 2017-05-22T11:25:00Z-2017-05-23T11:25:00Z

src_address = { ip: 192.0.2.1-192.0.2.254 }

src_address = { mac: 00:00:5E:00:53:00-00:00:5E:00:53:FF }

Condition value lists

When specifying values, you can use lists. A list contains one or more values for a field.

You can combine lists and ranges.

Lists use the following syntax:

value_1, value_2, ..., value_N, ...

Following value types support lists:

  • Integral
  • Enumeration
  • String value
  • IPv4 address
  • MAC address

The following are examples of lists:

event_id = 100, 110, 115, 127-150

technology = dpi, ids, nic

protocol = "ProfinetEtherType", "Loopback"

src_address = { ip: 192.0.2.1-192.0.2.254, 127.0.0.0/24, linklocal }

src_address = { mac: 00:00:5E:00:53:00-00:00:5E:00:53:10, 00:00:5E:00:53:FF }

Field names (event requests)

The following table summarizes field names that can be used in event requests:

Field names (event requests)

Field name

Value type

Description

mark

Integral

User mark

occurred

Date and time

Date and time when an event occurred

severity

Enumeration

Event severity

technology

Enumeration

Technology that generated the event

technology_rule

String value

Name of the rule that generated the event

src_address

Property bag

Source address

dst_address

Property bag

Destination address

protocol

String value

Protocol name

event_id

Integral

Event identifier

event_type_id

Integral

Event type identifier

monitoring_point

String value

Monitoring point

Property bag field names (event requests)

The following table summarizes field names can be used in property bags:

Field names (property bags)

Field name

Value type

Description

ip

IPv4 address

IPv4 address

port

Integral

Port

mac

MAC address

MAC address

vlan_id

Integral

Virtual LAN (VLAN) identifier

application

String value

Application layer address

Enumeration values

The following table summarizes enumeration values for the severity field:

Values for severity field

Value

Description

info

Info severity

warning

Warning severity

critical

Critical severity

The following table summarizes enumeration values for the technology field:

Values for technology field

Value

Description

nic

NIC technology (Network Integrity Control)

dpi

DPI technology (Deep Packet Inspection)

ids

IDS technology (Intrusion Detection System)

cc

CC technology (Command Control)

am

AM technology (Asset Management)

external

External technology

Maximum values for integral fields

The following table summarizes maximum values for integral fields:

Maximum values for integral fields

Field name

Maximum value

mark

7

event_id

2^64 - 1

event_type_id

2^64 - 1

port

65535

vlan_id

4095

Making event requests with filters

The following EventProviderService methods use filters:

  • GetItemsById

    You can specify a filter in the ItemsByIdRequest message.

  • RequestItems

    You can specify a filter in the Filter message.

The following is an example of using filters to get events with the GetItemsById method:

eventStub = event_provider_service_pb2_grpc.EventProviderStub(channel)

 

request = common_pb2.ItemsByIdRequest(

maxCount=3,

filter="filter: {severity = critical && monitoring_point = P }"

)

response = eventStub.GetItemsById(request)

for event in response:

print("\n\n")

print("Event:", event.eventId,

"| Severity:", event.severity,

"| At:", datetime.datetime.utcfromtimestamp(event.occurred.seconds).strftime('%Y-%m-%d %H:%M:%S'),

"| Monitoring point:", event.monitoringPoint,

"| Origin:", event.origin,

"| Title:", event.title

)

The following is an example of using a filter to get events with RequestItems method:

eventStub = event_provider_service_pb2_grpc.EventProviderStub(channel)

 

request = event_provider_service_pb2.Filter()

request.filter = "filter: {severity = critical && monitoring_point = P }"

 

ts_from = google_dot_protobuf_dot_timestamp__pb2.Timestamp()

ts_from.FromDatetime(datetime.datetime.now() - datetime.timedelta(days=1))

ts_to = google_dot_protobuf_dot_timestamp__pb2.Timestamp()

ts_to.FromDatetime(datetime.datetime.now())

getattr(request.timeSpan, 'from').CopyFrom(ts_from)

getattr(request.timeSpan, 'to').CopyFrom(ts_to)

 

# make async. request

response = eventStub.RequestItems(request)

cookie = response.cookie

request = common_pb2.Cookie(cookie=cookie)

keep_checking = True

while (keep_checking == True):

time.sleep(1)

response = eventStub.GetRequestState(request)

if (response.state != common_pb2.InProgress):

keep_checking = False

 

# retrieve events

request = event_provider_service_pb2.ItemsRequest()

request.cookie.cookie = cookie

request.window.maxCount = 3

response = eventStub.GetItems(request)

for event in response:

print("\n\n")

print("Event:", event.eventId,

"| Severity:", event.severity,

"| At:", datetime.datetime.utcfromtimestamp(event.occurred.seconds).strftime('%Y-%m-%d %H:%M:%S'),

"| Monitoring point:", event.monitoringPoint,

"| Title:", event.title

)

 

request = common_pb2.Cookie(cookie=cookie)

response = eventStub.CancelItemsRequest(request)