Getting events
This section explains how to get events using Kaspersky Industrial CyberSecurity for Networks API RPC calls.
Overview
Events are messages generated by Kaspersky Industrial CyberSecurity for Networks in response to suspicious industrial network traffic, detected attacks, and other security-related data.
You can get events from Kaspersky Industrial CyberSecurity for Networks by using the EventProvider service methods. This service is defined in the event_provider_service.proto file. Messages and enumerations are defined in the event_provider.proto, event_provider_service.proto, and common.proto files.
The EventProvider service has the following methods for getting events:
GetItemReturns a single event by its identifier.
GetItemsByIdReturns a specified number of events starting from a certain event (but not including this event). You can specify a filter for events. By default, events are sorted by event time stamps in descending order (most-recent events appear first).
This method is synchronous. The response time for this method depends on the number of requested events and the specified filter.
RequestItems,GetRequestState,GetItems, andCancelItemsRequestThis group of methods gets events asynchronously.
The
RequestItemsmethod requests a specific number of events in a certain time span. You can specify a filter for events.The
GetRequestStatemethod returns the state of the request.When the request is completed, the
GetItemsmethod gets the results of the request. You can call this method several times, specifying a number of events and a starting event.The
CancelItemsRequestmethod cancels the processing of a request (if processing is not yet complete) and frees resources allocated for the request. This method must be used when request results are no longer needed and to cancel requests.
Getting a single event by its identifier (example)
To get a single event by its identifier, use the GetItem method. This method returns an event.
In the following example, a stub requests an event with the identifier equal to 100.
eventStub = event_provider_service_pb2_grpc.EventProviderStub(channel)
# rpc GetItem(EventId) returns(Event); request = common_pb2.EventId(eventId=100) response = eventStub.GetItem(request) print("Event:", response.eventId, " At:", datetime.datetime.utcfromtimestamp(response.occurred.seconds).strftime('%Y-%m-%d %H:%M:%S') ) print(response) |
Getting several events (example)
To get several events, use the GetItemsById method. This method returns a stream of events. If you do not specify a starting event identifier, the method returns the specified number of the most-recent events.
In the following example, a stub requests three events, starting from an event with identifier equal to 100, but not including it. The response contains three events with identifiers 103, 102, and 101.
eventStub = event_provider_service_pb2_grpc.EventProviderStub(channel)
request = common_pb2.ItemsByIdRequest(startId=100, maxCount=3) 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 ) |
Getting several events asynchronously (example)
To get several events in a specified time span asynchronously, use the RequestItems, GetRequestState, GetItems, and CancelItemsRequest functions.
In the following example, a stub requests items that occurred during the last 24 hours (RequestItems) and gets a request Cookie. The stub then checks for the request completion once per second (GetRequestState). When the request is completed, the stub receives the 100 last events from the results (GetItems). Finally, the stub frees the resources allocated for the request (CancelItemsRequest).
eventStub = event_provider_service_pb2_grpc.EventProviderStub(channel)
#rpc RequestItems(Filter) returns(Cookie); request = event_provider_service_pb2.Filter() request.filter = "" # last 24 hours 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 is used to circumvent the 'for' keyword getattr(request.timeSpan, 'from').CopyFrom(ts_from) getattr(request.timeSpan, 'to').CopyFrom(ts_to) response = eventStub.RequestItems(request) print("eventStub.RequestItems response: ", response)
cookie = response.cookie #rpc GetRequestState(Cookie) returns(RequestStateResponse); request = common_pb2.Cookie(cookie=cookie) keep_checking = True while (keep_checking == True): print("Sleeping for 1 second") time.sleep(1) response = eventStub.GetRequestState(request) print("Request state:", response.state) if (response.state != common_pb2.InProgress): keep_checking = False
# rpc GetItems(ItemsRequest) returns(stream Event); request = event_provider_service_pb2.ItemsRequest() request.cookie.cookie = cookie request.window.maxCount = 100 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, "| Origin:", event.origin, "| Title:", event.title )
# rpc CancelItemsRequest(Cookie) returns(google.protobuf.Empty); request = common_pb2.Cookie(cookie=cookie) response = eventStub.CancelItemsRequest(request) |