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)

Page top