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, wherefield
is the name of the field affected by the condition andvalue
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 thefield = 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 the192.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 }
. - Single address (octets):
- 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 }
. - Six octets:
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 |
---|---|---|
|
Integral |
User mark |
|
Date and time |
Date and time when an event occurred |
|
Enumeration |
Event severity |
|
Enumeration |
Technology that generated the event |
|
String value |
Name of the rule that generated the event |
|
Property bag |
Source address |
|
Property bag |
Destination address |
|
String value |
Protocol name |
|
Integral |
Event identifier |
|
Integral |
Event type identifier |
|
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 |
---|---|---|
|
IPv4 address |
IPv4 address |
|
Integral |
Port |
|
MAC address |
MAC address |
|
Integral |
Virtual LAN (VLAN) identifier |
|
String value |
Application layer address |
Enumeration values
The following table summarizes enumeration values for the severity
field:
Values for severity field
Value |
Description |
---|---|
|
Info severity |
|
Warning severity |
|
Critical severity |
The following table summarizes enumeration values for the technology
field:
Values for technology field
Value |
Description |
---|---|
|
NIC technology (Network Integrity Control) |
|
DPI technology (Deep Packet Inspection) |
|
IDS technology (Intrusion Detection System) |
|
CC technology (Command Control) |
|
AM technology (Asset Management) |
|
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 |
---|---|
|
|
|
|
|
|
|
|
|
|
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) |