Contents
- Copyright
- About this guide
- About Kaspersky Industrial CyberSecurity for Networks API
- Quick start
- Generating gRPC code
- Establishing connections
- Getting and registering events
- Getting tags and subscribing to tag changes
- Getting configuration information
- Getting assets
- API Reference
- Services
- Messages
- ApplicationLayerAddress
- Asset
- AssetAddress
- AssetsUpdatedAfterRequest
- CommunicationData
- ConfigurationMetadata
- Cookie
- DeviceAddress
- DictionaryRequest
- Event
- EventDescriptor
- EventId
- Filter (events)
- Filter (tags)
- FixedNetworkAddress
- HashIdValue
- ItemsByIdRequest
- ItemsRequest
- KscConfiguration
- MessageParameter
- NewGenericEvent
- PlcConfiguration
- ProtocolConfiguration
- RequestStateResponse
- SubscriptionRequest
- Tag
- TagBriefInfo
- TagDescriptor
- TagEvent
- TagsRequest
- TimeSpan
- TransmissionWindow
- TransportAddress
- Version
- Enumerations
- AO Kaspersky Lab
- Information about third-party code
- Trademark notices
Copyright
Dear User,
Thank you for choosing Kaspersky Lab as your security software provider. We hope that this document helps you to use our product.
Attention! This document is the property of AO Kaspersky Lab (herein also referred to as Kaspersky Lab): all rights to this document are reserved by the copyright laws of the Russian Federation and by international treaties. Illegal reproduction and distribution of this document or parts hereof incur civil, administrative, or criminal liability under applicable law.
Any type of reproduction or distribution of any materials, including translations, is allowed only with the written permission of Kaspersky Lab.
This document, and graphic images related to it, may be used for informational, non-commercial, and personal purposes only.
Kaspersky Lab reserves the right to amend this document without additional notification.
Kaspersky Lab assumes no liability for the content, quality, relevance, or accuracy of any materials used in this document to which rights are held by third parties, or for any potential harms associated with use of the document.
Document revision date: 11.12.2019
© 2019 AO Kaspersky Lab. All Rights Reserved.
https://www.kaspersky.com
https://support.kaspersky.com
About this guide
This guide describes the main features of Kaspersky Industrial CyberSecurity for Networks API, the process of making RPC calls using Kaspersky Industrial CyberSecurity for Networks API, and also the API reference for Kaspersky Industrial CyberSecurity for Networks API.
The document is aimed at readers who are familiar with the Python programming language and understand software development in Windows or UNIX environment.
Page top
About Kaspersky Industrial CyberSecurity for Networks API
This chapter describes Kaspersky Industrial CyberSecurity for Networks API, its software requirements, and the contents of its distribution kit.
What is Kaspersky Industrial CyberSecurity for Networks API
Kaspersky Industrial CyberSecurity for Networks API provides RPC methods for getting and receiving data from Kaspersky Industrial CyberSecurity for Networks.
Kaspersky Industrial CyberSecurity for Networks API methods can do the following:
- Get information about Kaspersky Industrial CyberSecurity for Networks registered events.
- Send generic events to Kaspersky Industrial CyberSecurity for Networks.
- Get information about tags.
- Subscribe to tag change events.
- Get information about Kaspersky Industrial CyberSecurity for Networks configuration and version.
Kaspersky Industrial CyberSecurity for Networks API is based on Google Protocol Buffers and Google RPC (gRPC). The distribution kit of Kaspersky Industrial CyberSecurity for Networks API contains a set of .proto files. By compiling these .proto files, you can generate gRPC code in your chosen programming language, which would allow you to call Kaspersky Industrial CyberSecurity for Networks API methods.
Page top
Software requirements
This section contains information about hardware and software requirements of Kaspersky Industrial CyberSecurity for Networks API.
Software dependencies
Kaspersky Industrial CyberSecurity for Networks API has the following software dependencies:
Page top
Distribution kit contents
Kaspersky Industrial CyberSecurity for Networks API is delivered as an archive. The contents of this archive are called distribution kit in this document.
The table below lists the Kaspersky Industrial CyberSecurity for Networks API distribution kit contents.
Distribution kit contents
File name |
Description |
|---|---|
|
Definitions for AssetProvider service. |
|
Definitions for AssetProvider service. |
|
Definitions for common messages and enumerations. |
|
Definitions for ConfigurationProvider service. |
|
Definitions for ConfigurationProvider service. |
|
Definitions for DictionaryProvider service. |
|
Definitions for EventProvider service. |
|
Definitions for EventProvider service. |
|
Definitions for EventRegistrar service. |
|
Definitions for EventRegistrar service. |
|
Definitions for ProductFacade service. |
|
Definitions for TagNotifier service. |
|
Definitions for TagProvider service. |
|
Definitions for TagProvider service. |
|
Definitions for ProductFacade service. |
Quick start
Use the following procedure to prepare Kaspersky Industrial CyberSecurity for Networks API for use.
To prepare Kaspersky Industrial CyberSecurity for Networks API for use:
- Unpack the distribution kit contents.
- Generate gRPC code from .proto files.
- Use the remaining chapters in this guide to integrate other Kaspersky Industrial CyberSecurity for Networks API functionality, as required by your intended usage scenario.
Generating gRPC code
To generate classes for Kaspersky Industrial CyberSecurity for Networks API, you must compile .proto files.
Installing gRPC
Kaspersky Industrial CyberSecurity for Networks API uses gRPC. You must install gRPC and then invoke the protocol buffer compiler that comes with gRPC to compile .proto files.
To install gRPC, see the Quick Start guide for your preferred programming language on the gRPC documentation page.
Compiling .proto files
To compile .proto files, run the protocol buffer compiler that comes with gRPC. How you compile .proto files depends on your preferred programming language.
For Python, you can compile .proto files with the following commands:
python -m grpc_tools.protoc -Iprotos --python_out=. --grpc_python_out=. protos/asset_provider.proto python -m grpc_tools.protoc -Iprotos --python_out=. --grpc_python_out=. protos/asset_provider_service.proto python -m grpc_tools.protoc -Iprotos --python_out=. --grpc_python_out=. protos/common.proto python -m grpc_tools.protoc -Iprotos --python_out=. --grpc_python_out=. protos/configuration_provider.proto python -m grpc_tools.protoc -Iprotos --python_out=. --grpc_python_out=. protos/configuration_provider_service.proto python -m grpc_tools.protoc -Iprotos --python_out=. --grpc_python_out=. protos/dictionary_provider_service.proto python -m grpc_tools.protoc -Iprotos --python_out=. --grpc_python_out=. protos/event_provider.proto python -m grpc_tools.protoc -Iprotos --python_out=. --grpc_python_out=. protos/event_provider_service.proto python -m grpc_tools.protoc -Iprotos --python_out=. --grpc_python_out=. protos/event_registrar.proto python -m grpc_tools.protoc -Iprotos --python_out=. --grpc_python_out=. protos/event_registrar_service.proto python -m grpc_tools.protoc -Iprotos --python_out=. --grpc_python_out=. protos/product_facade_service.proto python -m grpc_tools.protoc -Iprotos --python_out=. --grpc_python_out=. protos/tag_notifier_service.proto python -m grpc_tools.protoc -Iprotos --python_out=. --grpc_python_out=. protos/tag_provider.proto python -m grpc_tools.protoc -Iprotos --python_out=. --grpc_python_out=. protos/tag_provider_service.proto python -m grpc_tools.protoc -Iprotos --python_out=. --grpc_python_out=. protos/version.proto |
For other programming languages, see the Quick Start guides on the gRPC documentation page.
Page top
Establishing connections
This section explains how to establish connection with Kaspersky Industrial CyberSecurity for Networks.
Overview
To make API calls, you must establish a connection with Kaspersky Industrial CyberSecurity for Networks (gRPC server). This connection is secure and uses certificates for authentication.
About certificates
To establish connections to the gRPC server, a client must use the following certificates and keys:
- gRPC server certificate (
product_facade_grpc_server.crt)This certificate is generated for the gRPC server host name by a system administrator and is used by a client to authenticate the server.
- gRPC server certificate authority (CA) certificate (
product_facade_grpc_ca.crt)This certificate is generated for the gRPC server host name and is used by the gRPC server to check client certificates.
This certificate can be bundled into the
client.crtfile or distributed separately. - Client certificate or a certificate bundle (
client.crt)The client certificate is generated for a client host name and is used by a client for authentication. The system administrator can distribute this file as a certificate or as a certificate bundle. The certificate bundle contains the client certificate generated for the client host name and all the intermediate certificates up to the root certificate
product_facade_grpc_ca.crt.It is assumed that this file contains a certificate bundle. If this file contains only the client certificate, you must create the certificate bundle yourself by grouping the client certificate, all the intermediate certificates (if any), and the gRPC server CA certificate into one file. The order of certificates in this file must form a certificate chain starting from the client certificate and up to the gRPC server CA certificate.
- Client key (
client.key)This is a private key for the client certificate.
Please contact your system administrator to obtain these files. All the certificates and keys must be in PEM format.
The certificates are generated for a specific host name. In this section, it is assumed that server certificates are generated for the kics4net.example.com host name and client certificates are generated for the client.example.com host name.
Establishing a secure connection to the gRPC server
To establish a connection to Kaspersky Industrial CyberSecurity for Networks, create a gRPC secure channel using the provided certificates and keys and provide this channel as a parameter when creating stubs.
The following example demonstrates establishing a secure connection to the gRPC server located at kics4net.example.com:13522 and creating an event stub that uses this channel.
with open('./certs/product_facade_grpc_server.crt', 'rt') as f: root_crt = f.read() with open('./certs/client.key', 'rt') as f: key = f.read() with open('./certs/client.crt', 'rt') as f: chain = f.read() channel_credentials = grpc.ssl_channel_credentials(root_crt, key, chain) channel = grpc.secure_channel('kics4net.example.com:13522', channel_credentials)
eventStub = event_provider_service_pb2_grpc.EventProviderStub(channel) |
Creating a secure port for connections from the gRPC server
To handle tag change events, you must run a service that accepts incoming connections from the Kaspersky Industrial CyberSecurity for Networks gRPC server. This service must use the same certificates and keys that are used for establishing connections to the gRPC server. The client certificate and key are used as server certificates (so that gRPC server can authenticate this service). The gRPC server certificate is used by this service to authenticate connections from the gRPC server.
The following example demonstrates how to create a secure port for listening to incoming connections from the gRPC server:
with open('./certs/product_facade_grpc_server.crt', 'rt') as f: root_crt = f.read() with open('./certs/client.key', 'rt') as f: key = f.read() with open('./certs/client.crt', 'rt') as f: chain = f.read()
server_credentials = grpc.ssl_server_credentials( private_key_certificate_chain_pairs=[(key, chain,)], root_certificates=root_crt, require_client_auth=True)
server.add_secure_port(address, server_credentials) |
Getting and registering events
This chapter explains how to get and register events using Kaspersky Industrial CyberSecurity for Networks API.
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) |
Registering events
This section explains how to register events using Kaspersky Industrial CyberSecurity for Networks API RPC calls.
Overview
Events are messages generated by Kaspersky Industrial CyberSecurity for Networks in response to triggered event rules.
In addition to getting events from Kaspersky Industrial CyberSecurity for Networks, you can register your own events in Kaspersky Industrial CyberSecurity for Networks. Kaspersky Industrial CyberSecurity for Networks handles these events as it does any other events.
You can register events in Kaspersky Industrial CyberSecurity for Networks by using the EventRegistrar service methods. This service is defined in the event_registrar_service.proto file. Messages and enumerations are defined in the event_registrar_service and common.proto files.
The EventRegistrar service has the following method for registering events:
PostGenericEventsRegisters one or more events.
This is a request-streaming RPC. You can send events to Kaspersky Industrial CyberSecurity for Networks synchronously or asynchronously.
Registering events (example)
To register events, use the PostGenericEvents method. This method receives a stream of generic events.
In the following example, a stub sends three identical events to Kaspersky Industrial CyberSecurity for Networks synchronously and asynchronously. In response, the PostGenericEvents method returns an empty protocol buffer (protobuf).
registrarStub = event_registrar_service_pb2_grpc.EventRegistrarStub(channel)
#rpc PostGenericEvents(stream NewGenericEvent) returns(google.protobuf.Empty);
# create an event sample_event = event_registrar_pb2.NewGenericEvent( eventTypeId=57, occurred=google_dot_protobuf_dot_timestamp__pb2.Timestamp(), triggeredRule="test rule", extraParams= [ common_pb2.MessageParameter(name="Custom_string", stringVal="Custom value 100"), common_pb2.MessageParameter(name="Custom_int64", int64Val=100), ] ) # set time sample_event.occurred.GetCurrentTime() # append an extra parameter extra_param = sample_event.extraParams.add() extra_param.name = "Custom_bool" extra_param.boolVal=True
# create an iterator from a list of events request = iter([sample_event, sample_event, sample_event])
# synchronous RPC call response = registrarStub.PostGenericEvents(request) print("Response is:", response)
# asynchronous RPC call response_future = registrarStub.PostGenericEvents.future(request) response = response_future.result() print("Response is:", response) |
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 = valueformat, wherefieldis the name of the field affected by the condition andvalueis 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 : valuesyntax instead of thefield = valuesyntax. - 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
0to 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/xxSubnet IPv4 address format always specifies a range of addresses. For example, the
192.0.2.0/24value is equivalent to the192.0.2.0-192.0.2.255range of addresses. - One of the literals in the following enumeration:
loopbackLoopback communication. IP addresses in the
127.0.0.0/8range.linklocalAutomatic Private IP Addressing. IP addresses in the
169.254.0.0/16range.ipv4multicastMulticast IP addresses. IP addresses in the
224.0.0.0/4range.privatenetworkPrivate network IP addresses. IP addresses in the
172.16.0.0/12range.internetAny 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:
GetItemsByIdYou can specify a filter in the
ItemsByIdRequestmessage.RequestItemsYou can specify a filter in the
Filtermessage.
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) |
Using sorting for events
This section explains how sorting works, describes sorting syntax for events, and provides sorting examples.
About sorting
Sorting is a special string that can be specified in RPC calls. Sorting can be combined with filters or used separately from them. A sorting is a group of conditions that specify the order of returned events.
For example, if you want to get events with the GetItemsById method of EventProviderService, and you also want those events to be sorted by event identifier (in descending order), then you can use the following sorting to do so:
sort: { event_id: desc } |
For examples of using sorting, see subsection "Making event requests with sorting" below.
Combining sorting with filters
Sorting can be combined with filters.
sort: { event_id: desc } filter: { event_id = 100, 101, 102, 103 } |
For an example of using filters with sorting, see subsection "Making event requests with sorting" below.
Sorting condition syntax
Sorting conditions use the following syntax:
field : order
Above, field is the name of the field affected by the condition, and order is one of the following two values:
ascField values are sorted in ascending order.
descField values are sorted in descending order.
For compound fields use the following syntax:
field.subfield : order
Above, field is the name of the field, subfield is the name of the subfield affected by the condition, and order is the order of sorting.
To combine several sorting conditions, separate them with commas (,):
field_1 : order, field_2 : order, field_3 : order
The following are examples of sorting conditions:
event_id : asc src_address.port: desc occurred : desc monitoring_point : asc, occurred : desc |
Field names (event requests)
The following table summarizes field names that can be used in event requests:
Field names (event requests)
Field name |
Subfields |
Description |
|---|---|---|
|
No |
Event title |
|
No |
Event description |
|
No |
User mark |
|
No |
Date and time when an event occurred |
|
No |
Event severity |
|
No |
Technology that generated the event |
|
No |
Name of the rule that generated the event |
|
Yes |
Source address |
|
Yes |
Destination address |
|
No |
Protocol name |
|
No |
Event identifier |
|
No |
Event type identifier |
|
No |
Monitoring point |
Subfield names
The following table summarizes subfield names can be used in sorting conditions for fields that can have subfields:
Subfield names
Field name |
Description |
|---|---|
|
IPv4 address |
|
Port |
|
MAC address |
|
Virtual LAN (VLAN) ID |
Making event requests with filters
The following EventProviderService methods use sorting:
GetItemsByIdYou can specify a sorting in the
ItemsByIdRequestmessage.RequestItemsYou can specify a sorting in the
Filtermessage.
The following is an example of using sorting to get events with the GetItemsById method:
eventStub = event_provider_service_pb2_grpc.EventProviderStub(channel)
request = common_pb2.ItemsByIdRequest( maxCount=3, filter="sort:{monitoring_point : asc, occurred : desc}" ) response = eventStub.GetItemsById(request) for event in response: print("\nEvent id:", event.eventId) |
The following is an example of combining sorting and 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} sort: {event_id: desc}" ) response = eventStub.GetItemsById(request) for event in response: print("\nEvent id:", event.eventId) |
Getting tags and subscribing to tag changes
This chapter explains how to get tags, subscribe to tag change events, and implement a service that receives tag change events.
Getting tags
This section explains how to get tags by using Kaspersky Industrial CyberSecurity for Networks API.
Overview
Tags are values that describe parameters of an industrial process. For example, a manufacturing process involving a thermal oxidizer may have temperature, residence time, and turbulence among many other tags.
You can get information about tags by using the TagProvider service methods. This service is defined in the tag_provider_service.proto file. Messages and enumerations are defined in the tag_provider.proto, tag_provider_service.proto, and common.proto files.
The TagProvider service has the following method for getting tags:
GetTagsReturns tags. You can specify a filter for tags.
This method is synchronous. The response time for this method depends on the number of requested tags.
Getting tags (example)
To get all tags, use the GetTags method and specify an empty filter. This method returns a stream of tags.
In the following example, a stub requests all tags.
tagStub = tag_provider_service_pb2_grpc.TagProviderStub(channel)
request = tag_provider_service_pb2.TagsRequest(filter = "") response = tagStub.GetTags(request)
for tag in response: if tag.HasField("boolVal"): value = tag.boolVal elif tag.HasField("int64Val"): value = tag.int64Val elif tag.HasField("doubleVal"): value = tag.doubleVal elif tag.HasField("stringVal"): value = tag.stringVal elif tag.HasField("binaryVal"): value = tag.binaryVal else: value = "No value" print("\n\n") print("Tag:", tag.id, "| Name:", tag.briefInfo.name, "| Description:", tag.briefInfo.description, "| Changed at:", datetime.datetime.utcfromtimestamp(tag.timestamp.seconds).strftime('%Y-%m-%d %H:%M:%S'), "| Value type: ", tag.WhichOneof("value"), "| Value: ", value) |
Using filters for tags
This section describes filters and filter syntax, and provides filter examples for tags.
About filters for tags
When getting tags, you can filter them by tag identifier and tag name. 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, when you get tags by using the GetTags method of TagProvider service, and you want to get information about tags with certain identifiers, then you can use the following filter to do so:
filter: { tag_id = 1001, 1002, 1003 } |
For examples of using filters for tags, see subsection "Making tag requests with filters" below.
Tag filter fields
Tag filters support basic conditions for following fields:
Field names (tag requests)
Field name |
Value type |
Description |
Condition example |
|---|---|---|---|
|
Integral |
Tag identifiers |
|
|
String |
Tag names |
|
Using lists and ranges
You can specify several tag identifiers, tag names, or tag descriptions using a list syntax:
value_1, value_2, ..., value_N, ...
The following are examples of list syntax:
tag_id = 1001, 1002, 1003 tag_name = Valve.State, Valve.Pressure |
For tag identifiers, you can also specify ranges using a range syntax:
value_1-value_N
The following are examples of range syntax:
tag_id = 1001-1100 |
You can also combine lists and ranges for tag identifiers, for example:
tag_id = 1001-1100, 2000-2050 |
Combining conditions
You can combine conditions using logical operators and parentheses:
filter: { (tag_id = 1001, 1002, 1003) || (tag_name = Valve.State, Valve.Pressure) } |
Making tag requests with filters
Following TagNotifier service method uses filters:
GetTagsYou can specify a filter in the
TagsRequestmessage.
In the following example, a stub requests tags with specified identifiers.
tagStub = tag_provider_service_pb2_grpc.TagProviderStub(channel)
#rpc GetTags(TagsRequest) returns(stream Tag);
request = tag_provider_service_pb2.TagsRequest(filter = "filter:{tag_id = 1000, 1001, 1002 }") response = tagStub.GetTags(request) for tag in response: print("\n\n") print("Tag:", tag.id, "| Name:", tag.briefInfo.name, "| Changed at:", datetime.datetime.utcfromtimestamp(tag.timestamp.seconds).strftime('%Y-%m-%d %H:%M:%S')) |
Using sorting for tags
This section describes sorting and sorting syntax for tags, and provides sorting examples.
About sorting
Sorting is a special string that can be specified in RPC calls. Sorting can be combined with filters or used separately from them. A sorting for tags is a group of conditions that specify the order of returned tags.
For example, if you want to get tags by using the GetTags method of TagProvider, and you also want those tags to be sorted by event identifier in descending order, then you can use the following sorting to do so:
sort: { tag_id: desc } |
For examples of using sorting, see subsection "Making tag requests with sorting" below.
Combining sorting with filters
Sorting can be combined with filters.
sort: { tag_id: desc } filter: { tag_id = 1000-1100 } |
For an example of using filters with sorting, see subsections "Making tag requests with sorting" below.
Sorting condition syntax
Sorting conditions use the following syntax:
field : order
where field is the name of the field affected by the condition, and order is one of two values:
ascField values are sorted in ascending order.
descField values are sorted in descending order.
The following are examples of sorting conditions:
tag_id : desc tag_name : asc tag_description : asc |
Field names (tag requests)
The following table summarizes field names that can be used in tag requests.
Field names (tag requests)
Field name |
Description |
|---|---|
|
Tag identifier |
|
Tag name |
|
Tag description |
Making tag requests with sorting
The following TagNotifier service method uses sorting:
GetTagsYou can specify a sorting in the
TagsRequestmessage.
The following is an example of using sorting to get tags with the GetTags method:
tagStub = tag_provider_service_pb2_grpc.TagProviderStub(channel)
request = tag_provider_service_pb2.TagsRequest(filter = "sort: { tag_id: asc, tag_name: desc, tag_description: asc}") response = tagStub.GetTags(request) for tag in response: print("\n\n") print("Tag:", tag.id, "| Name:", tag.briefInfo.name, "| Changed at:", datetime.datetime.utcfromtimestamp(tag.timestamp.seconds).strftime('%Y-%m-%d %H:%M:%S')) |
The following is an example of combining sorting and filters to get a subset of tags with the GetTags method:
tagStub = tag_provider_service_pb2_grpc.TagProviderStub(channel)
request = tag_provider_service_pb2.TagsRequest(filter = "filter:{tag_id=1000-2000} sort:{tag_id:desc}") response = tagStub.GetTags(request) for tag in response: print("\n\n") print("Tag:", tag.id, "| Name:", tag.briefInfo.name, "| Changed at:", datetime.datetime.utcfromtimestamp(tag.timestamp.seconds).strftime('%Y-%m-%d %H:%M:%S')) |
Subscribing to tag change events
This section explains how to subscribe to tag change events.
Overview
A tag change event is a message that contains a time stamp, and a list of tag identifiers whose values have changed. For each tag identifier, a new value of the tag is also returned.
You can subscribe to tag change events by using the TagProvider service methods. This service is defined in the tag_provider_service.proto file. Messages and enumerations are defined in the tag_provider.proto, tag_provider_service.proto, and common.proto files.
The TagProvider service has the following methods for subscribing to tag change events:
SubscribeTagNotifierSubscribes to tag change events.
You can specify a list of tag identifiers. Only events for the specified identifiers will be included in the subscription.
UnsubscribeNotifierRemoves an existing subscription.
Subscribing to tag change events (example)
To subscribe to tags, use the SubscribeTagNotifier method. In the following example, a stub makes a subscription request for tags with identifiers 1000, 1001, and 1002. Kaspersky Industrial CyberSecurity for Networks API will send events to the client.example.com:50051 address and port, where they must be handled by the TagNotifier service. After that, the stub waits for 10 seconds and unsubscribes from tag change events.
tagStub = tag_provider_service_pb2_grpc.TagProviderStub(channel)
#rpc SubscribeTagNotifier(SubscriptionRequest) returns(Cookie); #rpc UnsubscribeNotifier(Cookie) returns(google.protobuf.Empty);
listener = "client.example.com:50051"
tag_filter = tag_provider_service_pb2.Filter(tagIds=[1000, 1001, 1002])
request = tag_provider_service_pb2.SubscriptionRequest(address=listener, filter=tag_filter) response = tagStub.SubscribeTagNotifier(request) cookie = response.cookie
# wait for 10 seconds, then unsubscribe print("Sleeping for 10 seconds") time.sleep(10)
# unsubscribe print("Unsubscribing") request = common_pb2.Cookie(cookie=cookie) response = tagStub.UnsubscribeNotifier(request) |
Handling tag change events
This section explains how to implement a service that handles the tag change events sent by Kaspersky Industrial CyberSecurity for Networks.
Overview
When you subscribe to tag change events, you must specify an address where Kaspersky Industrial CyberSecurity for Networks has to send tag change events. To handle these messages, you must implement the OnNewTags method of the TagNotifier service and run the service. The service must listen for incoming messages on the specified address and port.
The TagNotifier service is defined in the tag_notifier_service.proto file. Messages and enumerations are defined in the tag_notifier_service.proto file.
The TagNotifier service has the following methods for handling messages with tag change events:
OnNewTagsThis method is called when a message with tag change event is received.
Handling tag change events (example)
The following is an example of a service that handles tag change events. It has an implementation of the OnNewTags method of the TagNotifier service, which prints the received tag change events.
For more information about implementing gRPC services, see the gRPC documentation.
from __future__ import print_function import datetime import time from concurrent import futures import grpc from google.protobuf import empty_pb2 as google_dot_protobuf_dot_empty__pb2 import tag_notifier_service_pb2 import tag_notifier_service_pb2_grpc
class TagNotifierServicer(tag_notifier_service_pb2_grpc.TagNotifierServicer):
def OnNewTags(self, request_iterator, context): # rpc OnNewTags(stream TagEvent) returns(google.protobuf.Empty); for tag_event in request_iterator: print("\n\n") print("Tag event at:", datetime.datetime.utcfromtimestamp(tag_event.timestamp.seconds).strftime('%Y-%m-%d %H:%M:%S'), "| Operation:", tag_event.operation, "| Monitoring point:", tag_event.monitoringPoint, "| From:", context.peer()) for tag in tag_event.tags: print(tag) return google_dot_protobuf_dot_empty__pb2.Empty()
def serve(address): server = grpc.server(futures.ThreadPoolExecutor(max_workers=10)) tag_notifier_service_pb2_grpc.add_TagNotifierServicer_to_server(TagNotifierServicer(), server) with open('./certs/product_facade_grpc_server.crt', 'rt') as f: root_crt = f.read() with open('./certs/client.key', 'rt') as f: key = f.read() with open('./certs/client.crt', 'rt') as f: chain = f.read()
server_credentials = grpc.ssl_server_credentials( private_key_certificate_chain_pairs=[(key, chain,)], root_certificates=root_crt, require_client_auth=True ) server.start()
SECONDS_IN_24H = 60 * 60 * 24 try: while True: time.sleep(SECONDS_IN_24H) except KeyboardInterrupt: print("Stopping...") server.stop(0)
if __name__ == '__main__': address = '[::]:50051' print("Serving on", address) serve(address)
|
Getting configuration information
This chapter explains how to obtain Kaspersky Industrial CyberSecurity for Networks configuration information, including:
- Kaspersky Industrial CyberSecurity for Networks configuration metadata
- Kaspersky Industrial CyberSecurity for Networks agent configuration
- Information about programmable logic controllers (PLCs)
- Protocol configuration for PLCs
- Information about available tags for PLCs and protocols
- Event descriptors
- Dictionaries
Getting Kaspersky Security Center agent configuration
This section explains how to obtain the Kaspersky Security Center agent configuration used by Kaspersky Industrial CyberSecurity for Networks.
Overview
Kaspersky Industrial CyberSecurity for Networks can be configured to provide configuration for Kaspersky Security Center agent.
You can get this configuration by using the ConfigurationProvider service methods. This service is defined in the configuration_provider_service.proto file. Messages and enumerations are defined in the configuration_provider.proto and configuration_provider_service.proto files.
The ConfigurationProvider service has the following method for getting Kaspersky Security Center agent configuration:
GetKscConfigurationReturns Kaspersky Security Center agent configuration.
Getting Kaspersky Security Center agent configuration (example)
To get Kaspersky Security Center agent configuration, use the GetKscConfiguration method. In the following example, a stub requests Kaspersky Security Center agent configuration.
configStub = configuration_provider_service_pb2_grpc.ConfigurationProviderStub(channel)
#rpc GetKscConfiguration(google.protobuf.Empty) returns(KscConfiguration);
response = configStub.GetKscConfiguration(google_dot_protobuf_dot_empty__pb2.Empty()) print(response) |
Getting Kaspersky Industrial CyberSecurity for Networks configuration
This section explains how to obtain Kaspersky Industrial CyberSecurity for Networks configuration by using Kaspersky Industrial CyberSecurity for Networks API RPC calls.
Overview
You can get Kaspersky Industrial CyberSecurity for Networks configuration by using the ConfigurationProvider service methods. This service is defined in the configuration_provider_service.proto file. Messages and enumerations are defined in the configuration_provider.proto and configuration_provider_service.proto files.
The ConfigurationProvider service has the following methods for getting Kaspersky Industrial CyberSecurity for Networks configuration:
GetConfigurationMetadataReturns current Kaspersky Industrial CyberSecurity for Networks configuration metadata, such as configuration version, Kaspersky Industrial CyberSecurity for Networks version, project name, and time stamp of the last configuration change.
GetPlcConfigurationReturns a list of PLCs and information about them, such as hash identifier, name, and type of PLC, and a list of protocols.
GetProtocolConfigurationReturns configuration for protocols of the specified PLC. This information includes protocol identifier, name, type, monitoring point name, device address, and transport address.
GetTagsForPlcReturns tag descriptors for the specified PLC. The tag descriptor includes information about a tag, such as tag identifier, name, description, tag value type, and measurement units.
GetTagsForProtocolReturns tag descriptors for the specified protocol. A tag descriptor includes information about a tag, such as tag identifier, name, description, tag value type, and measurement units.
GetEventDescriptorsReturns descriptors for event types. An event descriptor includes information about a specific type of events: event type identifier, event title, severity, technology that generated the event, and event description.
Getting configuration metadata (example)
To get configuration metadata, use the GetConfigurationMetadata method.
In the following example, a stub requests configuration metadata.
configStub = configuration_provider_service_pb2_grpc.ConfigurationProviderStub(channel)
#rpc GetConfigurationMetadata(google.protobuf.Empty) returns(ConfigurationMetadata);
response = configStub.GetConfigurationMetadata(google_dot_protobuf_dot_empty__pb2.Empty())
print("Configuration version:", response.configurationVersion, "| Project name:", response.projectName, "| Product version:", response.productVersion, "| Timestamp:", datetime.datetime.utcfromtimestamp(response.timestamp.seconds).strftime('%Y-%m-%d %H:%M:%S') ) |
Getting a list of PLCs (example)
To get a list of PLCs, use the GetPlcConfiguration method. In the following example, a stub requests a list of PLCs and prints the received information.
configStub = configuration_provider_service_pb2_grpc.ConfigurationProviderStub(channel)
#rpc GetPlcConfiguration(google.protobuf.Empty) returns(stream PlcConfiguration);
response = configStub.GetPlcConfiguration(google_dot_protobuf_dot_empty__pb2.Empty())
for plc in response: print("\n\n") print("PLC:", "| Hash id:", plc.hashId, "| Name:", plc.plcName, "| Type:", plc.plcType ) for protocol in plc.plcProtos: print("Protocol id:", protocol) |
Getting protocol configuration for a PLC (example)
To get configuration for all protocols of a certain PLC, use the GetProtocolConfiguration method.
In the following example, a stub requests protocol configuration and specifies hash identifier of a PLC (in this example, the value of this identifier is 1).
configStub = configuration_provider_service_pb2_grpc.ConfigurationProviderStub(channel)
#rpc GetProtocolConfiguration(HashIdValue) returns(stream ProtocolConfiguration);
request = configuration_provider_service_pb2.HashIdValue(hashId=1)
response = configStub.GetProtocolConfiguration(request)
for protocol in response: print("\n\n") print("Protocol", "| Hash id:", protocol.hashId, "| Name:", protocol.protocolName, "| Type:", protocol.protocolType)
if protocol.HasField("deviceAddress"): print("Device address:", "| Rack:", protocol.deviceAddress.rack, "| Slot:", protocol.deviceAddress.slot)
for taddr in protocol.transportAddresses: print("Transport address:", "| MAC:", taddr.mac, "| IP:", taddr.ip, "| Port:", taddr.port, "| Domain:", taddr.domainId) |
Getting tags for a PLC (example)
To get tag descriptors for the specified PLC, use the GetTagsForPlc method. In the following example, a stub requests tags for a specified hash identifier of a PLC (in this example, the value of this identifier is 1).
configStub = configuration_provider_service_pb2_grpc.ConfigurationProviderStub(channel)
#rpc GetTagsForPlc(HashIdValue) returns(stream TagDescriptor);
request = configuration_provider_service_pb2.HashIdValue(hashId=1)
response = configStub.GetTagsForPlc(request)
for tag_descriptor in response: print("Descriptor:", "| Id:", tag_descriptor.tagId, "| Name:", tag_descriptor.tagName, "| Value type:", tag_descriptor.tagType, "| Units:", tag_descriptor.measurementUnits, "| Description:", tag_descriptor.tagDescription) |
Getting tags for protocol (example)
To get tag descriptors for the specified protocol, use the GetTagsForProtocol method. In the following example, a stub requests tags for a specified hash identifier of the protocol (in this example, the value of this identifier is 1).
configStub = configuration_provider_service_pb2_grpc.ConfigurationProviderStub(channel)
#rpc GetTagsForProtocol(HashIdValue) returns(stream TagDescriptor);
request = configuration_provider_service_pb2.HashIdValue(hashId=1)
response = configStub.GetTagsForProtocol(request)
for tag_descriptor in response: print("Descriptor:", "| Id:", tag_descriptor.tagId, "| Name:", tag_descriptor.tagName, "| Value type:", tag_descriptor.tagType, "| Units:", tag_descriptor.measurementUnits, "| Description:", tag_descriptor.tagDescription) |
Getting event descriptors (example)
To get event descriptors, use the GetEventDescriptors method. In the following example, a stub requests event descriptors and prints the response.
configStub = configuration_provider_service_pb2_grpc.ConfigurationProviderStub(channel)
#rpc GetEventDescriptors(google.protobuf.Empty) returns(stream EventDescriptor);
response = configStub.GetEventDescriptors(google_dot_protobuf_dot_empty__pb2.Empty())
for event_descriptor in response: print("Event descriptor:", "| Type id:", event_descriptor.eventTypeId, "| Title:", event_descriptor.eventTitle, "| Severity:", event_descriptor.severity, "| Technology:", event_descriptor.technology, "| Description:", event_descriptor.eventDescription) |
Getting Kaspersky Industrial CyberSecurity for Networks version
This section explains how to obtain information about Kaspersky Industrial CyberSecurity for Networks version.
Overview
You can get information about Kaspersky Industrial CyberSecurity for Networks version by using the ProductFacade service methods. This service is defined in the product_facade_service.proto file. Messages are defined in the version.proto file.
The ProductFacade service has the following method for getting information about Kaspersky Industrial CyberSecurity for Networks version:
GetVersionReturns information about Kaspersky Industrial CyberSecurity for Networks version.
Getting Kaspersky Industrial CyberSecurity for Networks version (example)
To get Kaspersky Industrial CyberSecurity for Networks version, use the GetVersion method. In the following example, a stub requests Kaspersky Industrial CyberSecurity for Networks version.
versionStub = product_facade_service_pb2_grpc.ProductFacadeStub(channel)
response = versionStub.GetVersion(google_dot_protobuf_dot_empty__pb2.Empty()) print("Version", "| Major:", response.versionMajor, "| Minor:", response.versionMinor, "| Release:", response.versionRelease, "| Build:", response.versionBuild) |
Getting dictionary values
This section explains how to obtain dictionary values used by Kaspersky Industrial CyberSecurity for Networks.
Overview
Kaspersky Industrial CyberSecurity for Networks uses several dictionaries, including a dictionary of rule names, a dictionary of monitoring point names, and a dictionary of protocol names. All dictionary types are defined in the DictionaryType enumeration.
You can get values from the dictionaries by using the DictionaryProvider service methods. The service, messages, and enumerations are defined in the dictionary_provider_service.proto file.
The DictionaryProvider service has the following method for getting dictionary values:
GetDictionaryReturns values from the specified dictionary.
Getting dictionary values (example)
In the following example, a stub requests 100 values from the dictionary containing the rule names. You must specify the maximum count in the request.
configStub = configuration_provider_service_pb2_grpc.ConfigurationProviderStub(channel)
#rpc GetDictionary(DictionaryRequest) returns(stream google.protobuf.StringValue);
request = dictionary_provider_service_pb2.DictionaryRequest( type=dictionary_provider_service_pb2.Rules, maxCount=100)
response = dictStub.GetDictionary(request) for element in response: print(element.value) |
Getting specific dictionary values (example)
In the following example, a stub requests 10 values from the dictionary with the protocol names. The valuePrefix parameter specifies that only protocol names starting with "M300" must be returned.
configStub = configuration_provider_service_pb2_grpc.ConfigurationProviderStub(channel)
#rpc GetDictionary(DictionaryRequest) returns(stream google.protobuf.StringValue);
request = dictionary_provider_service_pb2.DictionaryRequest( type=dictionary_provider_service_pb2.Protocols, valuePrefix="M", maxCount=10)
response = dictStub.GetDictionary(request)
for element in response: print(element.value) |
Getting assets
This section explains how to get assets using Kaspersky Industrial CyberSecurity for Networks API RPC calls.
Overview
Assets are devices, connected to the industrial network. Kaspersky Industrial CyberSecurity for Networks monitors their activity and updates information about them, making it easier for an administrator to make security-related decisions.
You can get a list of assets from Kaspersky Industrial CyberSecurity for Networks by using the AssetProvider service. This service is defined in the asset_provider_service.proto file. Messages and enumerations are defined in the asset_provider.proto file.
The AssetProvider service has the following method for getting assets:
GetAssetsUpdatedAfterReturns a list of assets: either all available assets or assets that were updated after some specified time.
Getting a list of assets
To get a list of assets, use the GetAssetsUpdatedAfter method. See example below.
ts = timestamp_pb2.Timestamp() # Initialize time stamp object with the date a day before to read assets, changed for the last day. ts.FromDatetime(datetime.utcnow() - timedelta(minutes=1)) # Comment out this line to retrieve full list of assets.
# Initialize request object. request = asset_provider_pb2.AssetsUpdatedAfterRequest() # Set the time stamp to read updates from. request.updateTimestamp.CopyFrom(ts)
# Read whole list of updated assets asset_list = asset_provider.GetAssetsUpdatedAfter(request) for asset in asset_list: # Make an asset description, which contains the asset name and address information. # Asset name is first. asset_description = 'Asset: ' + asset.name # Then all the asset addresses are listed. for address in asset.addresses: asset_description += '\n\t' address_blocks = set() if len(address.mac) > 0: address_blocks.add('MAC: ' + address.mac) if len(address.ips) > 0: address_blocks.add('IP: ' + ', '.join(address.ips)) asset_description += '; '.join(address_blocks) print(asset_description) |
API Reference
This chapter covers the application programming interface (API) of Kaspersky Industrial CyberSecurity for Networks API.
Services
This section contains descriptions of services provided by Kaspersky Industrial CyberSecurity for Networks API.
AssetProvider
Kaspersky Industrial CyberSecurity for Networks asset provider service.
Defined in
This service is defined in the asset_provider_service.proto file.
Syntax
service AssetProvider
{
rpc GetAssetsUpdatedAfter(AssetsUpdatedAfterRequest) returns(stream Asset);
}
Service methods
The AssetProvider service has the following service methods.
AssetProvider service methods
Name |
Request message |
Response message |
Description |
|---|---|---|---|
|
|
Returns a list of assets registered in Kaspersky Industrial CyberSecurity for Networks and updated after the time, specified in AssetsUpdatedAfterRequest method. |
ConfigurationProvider
Kaspersky Industrial CyberSecurity for Networks configuration provider service.
Defined in
This service is defined in the configuration_provider_service.proto file.
Syntax
service ConfigurationProvider
{
rpc GetKscConfiguration(google.protobuf.Empty) returns(KscConfiguration);
rpc GetConfigurationMetadata(google.protobuf.Empty) returns(ConfigurationMetadata);
rpc GetPlcConfiguration(google.protobuf.Empty) returns(stream PlcConfiguration);
rpc GetProtocolConfiguration(HashIdValue) returns(stream ProtocolConfiguration);
rpc GetTagsForPlc(HashIdValue) returns(stream TagDescriptor);
rpc GetTagsForProtocol(HashIdValue) returns(stream TagDescriptor);
rpc GetEventDescriptors(google.protobuf.Empty) returns(stream EventDescriptor);
}
Service methods
The ConfigurationProvider service has the following service methods.
ConfigurationProvider service methods
Name |
Request message |
Response message |
Description |
|---|---|---|---|
|
|
Returns configuration for Kaspersky Security Center agent. |
|
|
|
Returns current Kaspersky Industrial CyberSecurity for Networks configuration metadata. |
|
|
|
|
Returns a list of PLCs and information about them. |
|
|
Returns configuration for protocols of the specified PLC. |
|
|
|
Returns tag descriptors for the specified PLC. |
|
|
|
Returns tag descriptors for the specified protocol. |
|
|
|
|
Returns descriptors for event types. |
Remarks
If no configuration is loaded into Kaspersky Industrial CyberSecurity for Networks, calling ConfigurationProvider service methods results in an error.
DictionaryProvider
Dictionary provider service. This service provides dictionary values used by Kaspersky Industrial CyberSecurity for Networks.
Defined in
This service is defined in the dictionary_provider_service.proto file.
Syntax
service DictionaryProvider
{
rpc GetDictionary(DictionaryRequest) returns(stream google.protobuf.StringValue);
}
Service methods
The DictionaryProvider service has the following service methods.
DictionaryProvider service methods
Name |
Request message |
Response message |
Description |
|---|---|---|---|
|
|
Returns a stream of values in a specified dictionary. |
EventProvider
Event provider service.
Defined in
This service is defined in the event_provider_service.proto file.
Syntax
service EventProvider
{
rpc GetItem(EventId) returns(Event);
rpc RequestItems(Filter) returns(Cookie);
rpc GetItems(ItemsRequest) returns(stream Event);
rpc GetRequestState(Cookie) returns(RequestStateResponse);
rpc CancelItemsRequest(Cookie) returns(google.protobuf.Empty);
rpc GetItemsById(ItemsByIdRequest) returns(stream Event);
}
Service methods
The EventProvider service has the following service methods.
EventProvider service methods
Name |
Request message |
Response message |
Description |
|---|---|---|---|
|
Returns a single event according to its identifier. Receives the event identifier and returns an event with the specified identifier. |
||
|
Makes an asynchronous request for a specific number of events in a certain time span. Receives the parameters of an event request and returns a request cookie. |
||
|
|
Returns the results of an asynchronous request. Receives a request cookie and range parameters, and returns a stream of events. After the events are received, you must make a |
|
|
Returns the state of an asynchronous request. Receives a request cookie and returns the status of the request. |
||
|
|
Cancels the processing of an asynchronous request (if processing is not yet complete) and frees resources allocated for the request. Receives a request cookie. |
|
|
|
Returns a specified number of events starting from a certain event (but not including this event). Receives request parameters (filter, identifier of the starting event, and maximum number of events) and returns a stream of events. |
EventRegistrar
Service that registers events in Kaspersky Industrial CyberSecurity for Networks.
Defined in
This service is defined in the event_registrar_service.proto file.
Syntax
service EventRegistrar
{
rpc PostGenericEvents(stream NewGenericEvent) returns(google.protobuf.Empty);
}
Service methods
The EventRegistrar service has the following service methods.
EventRegistrar service methods
Name |
Request message |
Response message |
Description |
|---|---|---|---|
|
|
|
Registers one or more events. Receives a stream of events. |
ProductFacade
Kaspersky Industrial CyberSecurity for Networks version provider service.
Defined in
This service is defined in the product_facade_service.proto file.
Syntax
service ProductFacade
{
rpc GetVersion(google.protobuf.Empty) returns (Version);
}
Service methods
The ProductFacade service has the following service methods.
ProductFacade service methods
Name |
Request message |
Response message |
Description |
|---|---|---|---|
|
|
Returns version information. |
TagNotifier
Service that handles requests with tag change events from Kaspersky Industrial CyberSecurity for Networks. This service must be implemented on the client side.
Defined in
This service is defined in the tag_notifier_service.proto file.
Syntax
service TagNotifier
{
rpc OnNewTags(stream TagEvent) returns(google.protobuf.Empty);
}
Service methods
The TagNotifier service has the following service methods.
TagNotifier service methods
Name |
Request message |
Response message |
Description |
|---|---|---|---|
|
|
|
This method is called when a message with a tag change event is received. Receives a stream of tag events (tags and operation types). |
TagProvider
Service that provides information about tags and handles subscription to tag change events.
Defined in
This service is defined in the tag_provider_service.proto file.
Syntax
service TagProvider
{
rpc SubscribeTagNotifier(SubscriptionRequest) returns(Cookie);
rpc UnsubscribeNotifier(Cookie) returns(google.protobuf.Empty);
rpc GetTags(TagsRequest) returns(stream Tag);
}
Service methods
TagProvider service has the following service methods.
TagProvider service methods
Name |
Request message |
Response message |
Description |
|---|---|---|---|
|
Subscribes to tag change events. Receives subscription settings (address and filter) and returns the subscription cookie. |
||
|
|
Removes an existing subscription to tag change events. Receives a request cookie. |
|
|
|
Returns a collection of tags. Receives tag request and returns a continuous stream of tags. |
Messages
This section contains descriptions of messages provided by Kaspersky Industrial CyberSecurity for Networks API.
ApplicationLayerAddress
Application-level address.
Defined in
This message is defined in the event_provider.proto file.
Syntax
message ApplicationLayerAddress
{
string address = 1;
string protocol = 2;
string protocolStack = 3;
DirectionType direction = 4;
string addressName = 5;
}
Fields
This message has the following fields.
ApplicationLayerAddress message fields
Type |
Name |
Tag |
Description |
|---|---|---|---|
|
|
|
Application layer address. |
|
|
|
Protocol name. |
|
|
|
Protocol stack. |
|
|
Communication direction. |
|
|
|
|
Address name. |
Asset
Asset descriptor for the AssetProvider service.
Defined in
This message is defined in the asset_provider.proto file.
Syntax
message Asset
{
string name = 1;
uint64 assetId = 2;
AssetStatus status = 3;
repeated AssetAddress addresses = 4;
AssetCategory category = 5;
AssetSecurityStatus securityStatus = 7;
google.protobuf.Timestamp lastSeen = 8;
google.protobuf.Timestamp lastModified = 9;
google.protobuf.Timestamp creationDate = 10;
bool isRouter = 11;
string os = 12;
string vendor = 13;
string model = 14;
string networkName = 15;
repeated string labels = 16;
map<string, string> parameters = 17;
}
Fields
The Asset message has the following fields.
Asset message fields
Rule Field |
Type |
Name |
Tag |
Description |
|---|---|---|---|---|
|
|
|
|
Name of the asset. |
|
|
|
|
Asset identifier. |
|
|
|
Current status of the asset. |
|
|
|
4 |
MAC and IP addresses of the asset. |
|
|
|
|
Device category of the asset. |
|
|
|
7 |
Current security status of the asset. |
|
|
|
|
8 |
Time when asset was last seen. |
|
|
|
9 |
Time when asset was last modified. |
|
|
|
10 |
Time when asset was added to the asset table. |
|
|
|
11 |
This parameter denotes whether the asset is a routing device. |
|
|
|
12 |
Name of the operating system of the asset. |
|
|
|
13 |
Name of the asset manufacturer. |
|
|
|
14 |
Name of the asset model and version information. |
|
|
|
15 |
Name used to represent the asset in the network. |
|
|
|
16 |
A list of labels assigned to the asset. |
|
|
|
17 |
Any additional parameters of the asset returned in pairs "Key, Value". |
AssetAddress
Asset address information.
Defined in
This message is defined in the asset_provider.proto file.
Syntax
message AssetAddress
{
string mac = 1;
repeated string ips = 2;
}
Fields
The AssetAddress message has the following fields.
AssetAddress message fields
Rule Field |
Type |
Name |
Tag |
Description |
|---|---|---|---|---|
|
|
|
|
MAC address of an asset. |
|
|
|
|
IP address or addresses of an asset. |
AssetsUpdatedAfterRequest
A message to define a time stamp for AssetProvider service in order to receive a list of assets, that were updated after specified time.
Defined in
This message is defined in the asset_provider.proto file.
Syntax
message AssetsUpdatedAfterRequest
{
google.protobuf.Timestamp updateTimestamp = 1;
}
Fields
The AssetsUpdatedAfterRequest message has the following fields.
AssetsUpdatedAfterRequest message fields
Type |
Name |
Tag |
Description |
|---|---|---|---|
|
|
Leave this field empty to get all available assets. |
CommunicationData
Network address descriptor.
Defined in
This message is defined in the event_provider.proto file.
Syntax
message CommunicationData
{
FixedNetworkAddress base = 1;
ApplicationLayerAddress application = 2;
}
Fields
This message has the following fields.
CommunicationData message fields
Type |
Name |
Tag |
Description |
|---|---|---|---|
|
|
Transport layer network address. |
|
|
|
Application layer address. |
ConfigurationMetadata
Kaspersky Industrial CyberSecurity for Networks configuration metadata.
Defined in
This message is defined in the configuration_provider.proto file.
Syntax
message ConfigurationMetadata
{
string configurationVersion = 1;
string projectName = 2;
google.protobuf.Timestamp timestamp = 3;
string productVersion = 4;
}
Fields
The ConfigurationMetadata message has the following fields.
ConfigurationMetadata message fields
Type |
Name |
Tag |
Description |
|---|---|---|---|
|
|
|
Current configuration version. |
|
|
|
Configuration project name. |
|
|
|
Time stamp of the last configuration change. |
|
|
|
Current version of Kaspersky Industrial CyberSecurity for Networks installation package. |
Cookie
Request and subscription cookie descriptor.
Defined in
This message is defined in the common.proto file.
Syntax
message Cookie
{
uint64 cookie = 1;
}
Fields
The Cookie message has the following fields.
Cookie message fields
Type |
Name |
Tag |
Description |
|---|---|---|---|
|
|
|
Cookie value. |
DeviceAddress
Device-specific address.
Defined in
This message is defined in the configuration_provider.proto file.
Syntax
message DeviceAddress
{
uint32 rack = 1;
uint32 slot = 2;
}
Fields
The DeviceAddress message has the following fields.
DeviceAddress message fields
Type |
Name |
Tag |
Description |
|---|---|---|---|
|
|
|
Rack number. |
|
|
|
Slot number. |
DictionaryRequest
Request for dictionary values.
Defined in
This message is defined in the dictionary_provider_service.proto file.
Syntax
message DictionaryRequest
{
DictionaryType type = 1;
string valuePrefix = 2;
uint32 maxCount = 3;
}
Fields
The DictionaryRequest message has the following fields.
DictionaryRequest message fields
Type |
Name |
Tag |
Description |
|---|---|---|---|
|
|
Type of the dictionary. |
|
|
|
|
Prefix for required values. |
|
|
|
Maximum number of returned records. |
Event
Descriptor of an event or an incident. The incident is an event with child events.
Defined in
This message is defined in the event_provider.proto file.
Syntax
message Event
{
uint64 eventId = 1;
google.protobuf.Timestamp occurred = 3;
Technology technology = 5;
Severity severity = 6;
string title = 7;
string description = 8;
uint32 userMark = 13;
repeated MessageParameter extraParams = 14;
string monitoringPoint = 15;
string triggeredRuleId = 16;
Origin origin = 17;
uint64 eventTypeId = 18;
repeated CommunicationData communicationData = 22;
UserState userState = 23;
uint32 aggregateCount = 24;
google.protobuf.Timestamp closed = 25;
google.protobuf.Timestamp lastSeen = 26;
repeated uint64 children = 27;
}
Fields
The Event message has the following fields.
Event message fields
Rule Field |
Type |
Name |
Tag |
Description |
|---|---|---|---|---|
|
|
|
|
Event identifier. |
|
|
|
|
Time stamp when the event occurred. |
|
|
|
Analysis technology type associated with the event. |
|
|
|
|
Event severity. |
|
|
|
|
|
Event title. |
|
|
|
|
Event description. |
|
|
|
|
User mark. |
|
|
|
Extra parameters. |
|
|
|
|
|
Monitoring point that generated the event. |
|
|
|
|
Identifier of the rule that triggered the event. |
|
|
|
Event origin. |
|
|
|
|
|
Event type identifier. |
|
|
|
Stacks of protocols and network addresses associated with the event. |
|
|
|
|
Event status. |
|
|
|
|
|
Number of times the event was triggered. |
|
|
|
|
Time stamp when either the event received Resolved status or its timer stopped being regenerated. |
|
|
|
|
Time stamp when the event was last triggered. |
|
|
|
|
Child events added to an event (incident). |
EventDescriptor
Event type descriptor for configuration provider service.
Defined in
This message is defined in the configuration_provider.proto file.
Syntax
message EventDescriptor
{
uint64 eventTypeId = 1;
string eventTitle = 2;
string eventDescription = 3;
Severity severity = 4;
event_provider.Technology technology = 5;
}
Fields
The EventDescriptor message has the following fields.
EventDescriptor message fields
Type |
Name |
Tag |
Description |
|---|---|---|---|
|
|
|
Event type identifier. |
|
|
|
Title for events of this type. |
|
|
|
Description for events of this type. |
|
|
Severity for events of this type. |
|
|
|
Analysis technology type associated with events of this type. |
EventId
Request for an event by identifier.
Defined in
This message is defined in the common.proto file.
Syntax
message EventId
{
uint64 eventId = 1;
}
Fields
The EventId message has the following fields.
EventId message fields
Type |
Name |
Tag |
Description |
|---|---|---|---|
|
|
|
Identifier of an event. |
Filter (events)
Parameters of an asynchronous event request.
Defined in
This message is defined in the event_provider_service.proto file.
Syntax
message Filter
{
string filter = 1;
TimeSpan timeSpan = 2;
}
Fields
The Filter message has the following fields.
Filter message fields
Type |
Name |
Tag |
Description |
|---|---|---|---|
|
|
|
Filter for events. |
|
|
Time interval for requested events. |
Filter (tags)
Filter for tag subscription request.
Defined in
This message is defined in the tag_provider_service.proto file.
Syntax
message Filter
{
repeated uint64 tagIds = 1;
}
Fields
The Filter message has the following fields.
Filter message fields
Rule Field |
Type |
Name |
Tag |
Description |
|---|---|---|---|---|
|
uint64 |
|
|
Tag identifiers. |
FixedNetworkAddress
Transport layer network address descriptor.
Defined in
This message is defined in the event_provider.proto file.
Syntax
message FixedNetworkAddress
{
string srcMac = 1;
string srcPort = 2;
string srcIp = 3;
string dstMac = 4;
string dstPort = 5;
string dstIp = 6;
EthernetProtocolType etherType = 7;
Ipv4ProtocolType ipv4Type = 8;
string vlanId = 9;
}
Fields
This message has the following fields.
FixedNetworkAddress message fields
Type |
Name |
Tag |
Description |
|---|---|---|---|
|
|
|
Source MAC address. |
|
|
|
Source port. |
|
|
|
Source IP address. |
|
|
|
Destination MAC address. |
|
|
|
Destination port. |
|
|
|
Destination IP address. |
|
|
Ethernet protocol type. |
|
|
|
IPv4 protocol type. |
|
|
|
|
Virtual LAN (VLAN) identifier. |
HashIdValue
Descriptor of a request made by using a hash identifier.
Defined in
This message is defined in the configuration_provider_service.proto file.
Syntax
message HashIdValue
{
uint64 hashId = 1;
}
Fields
The HashIdValue message has the following fields.
HashIdValue message fields
Type |
Name |
Tag |
Description |
|---|---|---|---|
|
|
|
Hash identifier value. |
ItemsByIdRequest
Request of items by identifier.
Defined in
This message is defined in the common.proto file.
Syntax
message ItemsByIdRequest
{
string filter = 1;
uint64 startId = 2;
int32 maxCount = 3;
}
Fields
The ItemsByIdRequest message has the following fields.
ItemsByIdRequest message fields
Type |
Name |
Tag |
Description |
|---|---|---|---|
|
|
|
Filter for items. |
|
|
|
Identifier of the starting item (this item is not included). If this value is |
|
|
|
Maximum number of items that must be retrieved. |
ItemsRequest
Parameters for retrieving the results of an asynchronous events request.
Defined in
This message is defined in the event_provider_service.proto file.
Syntax
message ItemsRequest
{
Cookie cookie = 1;
TransmissionWindow window = 2;
}
Fields
The ItemsRequest message has the following fields.
ItemsRequest message fields
Type |
Name |
Tag |
Description |
|---|---|---|---|
|
|
Cookie of the request. |
|
|
|
Range of events to retrieve. |
KscConfiguration
Kaspersky Security Center agent configuration.
Defined in
This message is defined in the configuration_provider.proto file.
Syntax
message KscConfiguration
{
string filter = 1;
uint32 maxEventsPerDay = 2;
}
Fields
The KscConfiguration message has the following fields.
KscConfiguration message fields
Type |
Name |
Tag |
Description |
|---|---|---|---|
|
|
|
Filter for events. |
|
|
|
Maximum number of events to send to Kaspersky Security Center per day. |
MessageParameter
Named message parameter descriptor.
Defined in
This message is defined in the common.proto file.
Syntax
message MessageParameter
{
string name = 1;
oneof value
{
int64 int64Val = 2;
double doubleVal = 3;
string stringVal = 4;
bytes binaryVal = 5;
bool boolVal = 6;
}
}
Fields
The MessageParameter message has the following fields.
MessageParameter message fields
Rule Field |
Type |
Name |
Tag |
Description |
|---|---|---|---|---|
|
string |
|
|
Parameter name. |
|
|
|
|
Value of the parameter. |
|
|
|
|
Int64 value. |
|
|
|
|
Double value. |
|
|
|
|
String value. |
|
|
|
|
Binary value. |
|
|
|
|
Boolean value. |
NewGenericEvent
Generic event descriptor for event registrar service.
Defined in
This message is defined in the event_registrar.proto file.
Syntax
message NewGenericEvent
{
uint64 eventTypeId = 1;
google.protobuf.Timestamp occurred = 2;
string triggeredRule = 4;
repeated MessageParameter extraParams = 5;
}
Fields
The NewGenericEvent message has the following fields.
NewGenericEvent message fields
Rule Field |
Type |
Name |
Tag |
Description |
|---|---|---|---|---|
|
|
|
|
Identifier of the event type. |
|
|
|
|
Time stamp when the event occurred. |
|
|
|
|
Name of the triggered rule (if any). |
|
|
|
Optional message parameters. |
PlcConfiguration
Programmable logic controller (PLC) configuration.
Defined in
This message is defined in the configuration_provider.proto file.
Syntax
message PlcConfiguration
{
uint64 hashId = 1;
string plcType = 2;
string plcName = 3;
repeated uint64 plcProtos = 4;
}
Fields
The PlcConfiguration message has the following fields.
PlcConfiguration message fields
Rule Field |
Type |
Name |
Tag |
Description |
|---|---|---|---|---|
|
|
|
|
Unique identifier of the PLC. |
|
|
|
|
Type of the PLC. |
|
|
|
|
Name of the PLC. |
|
|
|
|
List of hash identifiers of the protocols configured for this PLC. |
ProtocolConfiguration
Protocol configuration descriptor.
Defined in
This message is defined in the configuration_provider.proto file.
Syntax
message ProtocolConfiguration
{
uint64 hashId = 1;
string protocolType = 2;
string protocolName = 3;
repeated TransportAddress transportAddresses = 4;
DeviceAddress deviceAddress = 5;
}
Fields
The ProtocolConfiguration message has the following fields.
ProtocolConfiguration message fields
Rule Field |
Type |
Name |
Tag |
Description |
|---|---|---|---|---|
|
|
|
|
Hash identifier of the protocol. |
|
|
|
|
Protocol type. |
|
|
|
|
Protocol name. |
|
|
|
Transport address of the protocol. |
|
|
|
|
Device-specific address of the protocol. |
RequestStateResponse
Status of an asynchronous event request.
Defined in
This message is defined in the event_provider_service.proto file.
Syntax
message RequestStateResponse
{
RequestState state = 2;
}
Fields
The RequestStateResponse message has the following fields.
RequestStateResponse message fields
Type |
Name |
Tag |
Description |
|---|---|---|---|
|
|
Request status. |
SubscriptionRequest
Tag subscription request parameters.
Defined in
This message is defined in the tag_provider_service.proto file.
Syntax
message SubscriptionRequest
{
string address = 1;
Filter filter = 2;
}
Fields
The SubscriptionRequest message has the following fields.
SubscriptionRequest message fields
Type |
Name |
Tag |
Description |
|---|---|---|---|
|
|
|
Address and port of the remote subscriber. |
|
|
Filter for tags (tag identifiers). If this field is empty, all tags are included in the subscription. |
Tag
Tag descriptor for the TagProvider service.
Defined in
This message is defined in the tag_provider.proto file.
Syntax
message Tag
{
uint64 id = 1;
google.protobuf.Timestamp timestamp = 2;
TagBriefInfo briefInfo = 3;
oneof value
{
bool boolVal = 20;
int64 int64Val = 21;
double doubleVal = 23;
string stringVal = 24;
bytes binaryVal = 25;
}
}
Fields
The Tag message has the following fields.
Tag message fields
Rule Field |
Type |
Name |
Tag |
Description |
|---|---|---|---|---|
|
uint64 |
|
|
Tag identifier. |
|
|
|
|
Time stamp when the tag was last encountered in the traffic. |
|
|
|
Information about the tag. Available only for the GetTags method of the TagProvider service. |
|
|
|
|
|
Value of the tag. |
|
|
|
|
Boolean value. |
|
|
|
|
Int64 value. |
|
|
|
|
Double value. |
|
|
|
|
String value. |
|
|
|
|
Binary value. |
TagBriefInfo
Information about a tag.
Defined in
This message is defined in the tag_provider.proto file.
Syntax
message TagBriefInfo
{
string name = 1;
string description = 2;
}
Fields
The TagBriefInfo message has the following fields.
TagBriefInfo message fields
Type |
Name |
Tag |
Description |
|---|---|---|---|
|
|
|
Tag name. |
|
|
|
Tag description. |
TagDescriptor
Tag descriptor for the ConfigurationProvider service.
Defined in
This message is defined in the configuration_provider.proto file.
Syntax
message TagDescriptor
{
uint64 tagId = 1;
string tagName = 2;
string tagDescription = 3;
string tagType = 4;
string measurementUnits = 5;
}
Fields
The TagDescriptor message has the following fields.
TagDescriptor message fields
Type |
Name |
Tag |
Description |
|---|---|---|---|
|
|
|
Tag identifier. |
|
|
|
Tag name. |
|
|
|
Tag description. |
|
|
|
Tag type. |
|
|
|
Measurement units for tag value. |
TagEvent
Descriptor of a tag event.
Defined in
This message is defined in the tag_notifier_service.proto file.
Syntax
message TagEvent
{
repeated Tag tags = 1;
Operation operation = 2;
google.protobuf.Timestamp timestamp = 3;
string monitoringPoint = 4;
}
Fields
The TagEvent message has the following fields.
TagEvent message fields
Rule Field |
Type |
Name |
Tag |
Description |
|---|---|---|---|---|
|
|
|
Tags associated with the tag event. |
|
|
|
|
Operation type of the tag event. |
|
|
|
|
|
Time stamp when the tags were last encountered in the traffic. |
|
|
|
|
Monitoring point where the tags were encountered in the traffic. |
TagsRequest
Request for tags.
Defined in
This message is defined in the tag_provider_service.proto file.
Syntax
message TagsRequest
{
string filter = 1;
}
Fields
The TagsRequest message has the following fields.
TagsRequest message fields
Type |
Name |
Tag |
Description |
|---|---|---|---|
|
|
|
Filter for tags. |
TimeSpan
Time interval for requested events.
Defined in
This message is defined in the event_provider_service.proto file.
Syntax
message TimeSpan
{
google.protobuf.Timestamp from = 1;
google.protobuf.Timestamp to = 2;
}
Fields
The TimeSpan message has the following fields.
TimeSpan message fields
Type |
Name |
Tag |
Description |
|---|---|---|---|
|
|
|
Time stamp of the start of the interval. The specified value is included in the interval. |
|
|
|
Time stamp of the end of the interval. The specified value is included in the interval. |
TransmissionWindow
Range of events for an asynchronous events request.
Defined in
This message is defined in the common.proto file.
Syntax
message TransmissionWindow
{
uint64 startIndex = 1;
uint32 maxCount = 2;
}
Fields
The TransmissionWindow message has the following fields.
TransmissionWindow message fields
Type |
Name |
Tag |
Description |
|---|---|---|---|
|
|
|
Index of the first item. |
|
|
|
Maximum count of items to retrieve. |
TransportAddress
Transport address descriptor.
Defined in
This message is defined in the configuration_provider.proto file.
Syntax
message TransportAddress
{
string mac = 1;
string ip = 3;
string port = 4;
string domainId = 5;
}
Fields
The TransportAddress message has the following fields.
TransportAddress message fields
Type |
Name |
Tag |
Description |
|---|---|---|---|
|
|
|
MAC address |
|
|
|
IP address |
|
|
|
Port |
|
|
|
Domain identifier |
Version
Information about the Kaspersky Industrial CyberSecurity for Networks version.
Defined in
This message is defined in the version.proto file.
Syntax
message Version
{
uint32 versionMajor = 1;
uint32 versionMinor = 2;
uint32 versionRelease = 3;
uint32 versionBuild = 4;
}
Fields
The Version message has the following fields.
Version message fields
Type |
Name |
Tag |
Description |
|---|---|---|---|
|
|
|
Major version number. |
|
|
|
Minor version number. |
|
|
|
Release version flag. |
|
|
|
Build number. |
Enumerations
This section contains descriptions of enumerations provided by Kaspersky Industrial CyberSecurity for Networks API.
AssetCategory
Asset category types.
Defined in
This enumeration is defined in the asset_provider.proto file.
Syntax
enum AssetCategory
{
Unused = 0;
ScadaHmi = 17;
Rpa = 18;
Server = 19;
Workstation = 20;
Plc = 21;
EngineeringStation = 22;
MobileDevice = 23;
NetworkDevice = 24;
Other = 25;
}
Fields
This enumeration defines the following values.
AssetCategory message fields
Name |
Value |
Description |
|---|---|---|
|
0 |
This value is returned when an asset doesn't have a specified category. |
|
17 |
Computers with installed software for human-machine interface (HMI) systems or SCADA systems. |
|
18 |
Intelligent electronic device (IED). |
|
19 |
Devices with server software installed. |
|
20 |
Desktop personal computers or operator workstations. |
|
21 |
Programmable logic controllers. |
|
22 |
Computers with installed software to be used by ICS engineers. |
|
23 |
Portable electronic devices with computer functionality. |
|
24 |
Network equipment (for example, routers, switches). |
|
25 |
Devices that do not fall into the categories described above. |
AssetSecurityStatus
Security types, assigned to an asset depending on the events associated with it.
Defined in
This enumeration is defined in the asset_provider.proto file.
Syntax
enum AssetSecurityStatus
{
UnknownAssetSecurityStatus = 0;
Ok = 1;
Warning = 2;
Critical = 3;
}
Fields
This enumeration defines the following values.
AssetSecurityStatus message fields
Name |
Value |
Description |
|---|---|---|
|
0 |
Security status of the asset is unknown. |
|
1 |
There are no unprocessed events associated with the asset or there are only events with the |
|
2 |
There are unprocessed events associated with the asset with the |
|
3 |
There are unprocessed events associated with the asset with the |
AssetStatus
Asset status types.
Defined in
This enumeration is defined in the asset_provider.proto file.
Syntax
enum AssetStatus
{
UnknownAssetStatus = 0;
Unauthorized = 1;
Recognized = 2;
Archived = 3;
}
Fields
This enumeration defines the following values.
AssetStatus message fields
Name |
Value |
Description |
|---|---|---|
|
0 |
Asset status is unknown. |
|
1 |
Asset has Unauthorized status. |
|
2 |
Asset has Recognized status. |
|
3 |
Asset has Archived status. |
DictionaryType
Kaspersky Industrial CyberSecurity for Networks dictionary types.
Defined in
This enumeration is defined in the dictionary_provider_service.proto file.
Syntax
enum DictionaryType
{
Protocols = 0;
Rules = 1;
MonitoringPoints = 2;
}
Values
This enumeration defines the following values.
DictionaryType enumeration values
Name |
Value |
Description |
|---|---|---|
|
|
Protocols dictionary. |
|
|
Rules dictionary. |
|
|
Monitoring points dictionary. |
DirectionType
Direction that communication takes.
Defined in
This enumeration is defined in the event_provider.proto file.
Syntax
enum DirectionType
{
Source = 0;
Destination = 1;
}
Values
This enumeration defines the following values.
DirectionType enumeration values
Name |
Value |
Description |
|---|---|---|
|
|
Source of the communication. |
|
|
Destination of the communication. |
EthernetProtocolType
Ethernet protocol types.
Defined in
This enumeration is defined in the event_provider.proto file.
Syntax
enum EthernetProtocolType
{
UnknownEthernetProtocolType = 0;
Ip = 1;
Arp = 2;
RevArp = 3;
At = 4;
AArp = 5;
Vlan = 6;
Ipx = 7;
IpV6 = 8;
Loopback = 9;
GooseEtherType = 10;
SampledValuesEtherType = 11;
ProfinetEtherType = 12;
OldVlan = 13;
Lldp = 14;
ProsoftSystemsDeviceDiscovery = 15;
}
Values
This enumeration defines the following values.
EthernetProtocolType enumeration values
Name |
Value |
Description |
|---|---|---|
|
|
Unknown ethernet protocol type. |
|
|
IP protocol. |
|
|
Address Resolution Protocol (ARP). |
|
|
Reverse ARP. |
|
|
AppleTalk protocol. |
|
|
AppleTalk ARP. |
|
|
IEEE 802.1Q VLAN tagging. |
|
|
IPX protocol. |
|
|
IP protocol version 6. |
|
|
Loopback. |
|
|
Goose. |
|
|
Sampled values. |
|
|
Profinet. |
|
|
VLAN protocol types. |
|
|
LLDP protocol type. |
|
|
Protocol type for discovering ProSoft devices. |
Ipv4ProtocolType
IP protocol types.
Defined in
This enumeration is defined in the event_provider.proto file.
Syntax
enum Ipv4ProtocolType
{
UnknownIpv4ProtocolType = 0;
Udp = 1;
Tcp = 2;
}
Values
This enumeration defines the following values.
IpProtocolType enumeration values
Name |
Value |
Description |
|---|---|---|
|
|
Unknown IPv4 protocol type. |
|
|
UDP protocol. |
|
|
TCP protocol. |
Operation
Operations associated with tags.
Defined in
This enumeration is defined in the tag_notifier_service.proto file.
Syntax
enum Operation
{
Read = 0;
Write = 1;
}
Values
This enumeration defines the following values.
Operation enumeration values
Name |
Value |
Description |
|---|---|---|
|
|
Read operation. |
|
|
Write operation. |
Origin
Event origins.
Defined in
This enumeration is defined in the event_provider.proto file.
Syntax
enum Origin
{
UnknownOrigin = 0;
System = 1;
User = 2;
}
Values
This enumeration defines the following values.
Origin enumeration values
Name |
Value |
Description |
|---|---|---|
|
|
Event has unknown origin. |
|
|
System origin. |
|
|
User origin. |
RequestState
Asynchronous request states.
Defined in
This enumeration is defined in the common.proto file.
Syntax
enum RequestState
{
InProgress = 0;
Completed = 1;
Cancelled = 2;
Failed = 3;
DataNotFound = 4;
}
Values
This enumeration defines the following values.
RequestState enumeration values
Name |
Value |
Description |
|---|---|---|
|
|
Request is in progress. |
|
|
Request was successfully completed. |
|
|
Request was canceled. |
|
|
Request failed. |
|
|
Request was successfully completed, but data was not found. |
Severity
Event severity types.
Defined in
This enumeration is defined in the common.proto file.
Syntax
enum Severity
{
Info = 0;
Warning = 1;
Critical = 2;
}
Values
This enumeration defines the following values.
Severity enumeration values
Name |
Value |
Description |
|---|---|---|
|
|
Information event. |
|
|
Warning event. |
|
|
Critical event. |
Technology
Analysis technology types associated with events.
Defined in
This enumeration is defined in the event_provider.proto file.
Syntax
enum Technology
{
Dpi = 0;
Nic = 1;
Ids = 2;
External = 3;
Cc = 4;
Am = 5;
}
Values
This enumeration defines the following values.
Technology enumeration values
Name |
Value |
Description |
|---|---|---|
|
|
Event was generated as a result of analysis with DPI technology (Deep Packet Inspection). |
|
|
Event was generated as a result of analysis with NIC technology (Network Integrity Control). |
|
|
Event was generated as a result of analysis with IDS technology (Intrusion Detection System). |
|
|
Event was generated as a result of analysis with External technology (EXT, external systems). |
|
|
Event was generated as a result of analysis with CC technology (Command Control). |
|
|
Event was generated as a result of analysis with AM technology (Asset Management). |
UserState
Status of an event.
Defined in
This enumeration is defined in the event_provider.proto file.
Syntax
enum UserState
{
Proposed = 0;
Active = 1;
Resolved = 2;
}
Values
This enumeration defines the following values.
UserState enumeration values
Name |
Value |
Description |
|---|---|---|
|
|
Corresponds to the New event status. It is automatically assigned to all events when they are registered in Kaspersky Industrial CyberSecurity for Networks. |
|
|
Corresponds to the In progress event status. It is assigned by a user to the events that are being processed. |
|
|
Corresponds to the Resolved event status. It is assigned by a user to the events that were processed. |
AO Kaspersky Lab
Kaspersky Lab is a world-renowned vendor of systems protecting computers against digital threats, including viruses and other malware, unsolicited email (spam), and network and hacking attacks.
In 2008, Kaspersky Lab was rated among the world’s top four leading vendors of information security software solutions for end users (IDC Worldwide Endpoint Security Revenue by Vendor). Kaspersky Lab is the preferred vendor of computer protection systems for home users in Russia (IDC Endpoint Tracker 2014).
Kaspersky Lab was founded in Russia in 1997. It has since grown into an international group of companies with 38 offices in 33 countries. The company employs more than 3,000 skilled professionals.
Products. Kaspersky Lab products provide protection for all systems, from home computers to large corporate networks.
The personal product range includes security applications for desktop, laptop, and tablet computers, smartphones and other mobile devices.
The company offers protection and control solutions and technologies for workstations and mobile devices, virtual machines, file and web servers, mail gateways, and firewalls. The company's portfolio also features specialized products providing protection against DDoS attacks, protection for industrial control systems, and prevention of financial fraud. Used in conjunction with centralized management tools, these solutions ensure effective automated protection for companies and organizations of any size against computer threats. Kaspersky Lab products are certified by major test laboratories, compatible with software from diverse vendors, and optimized to run on many hardware platforms.
Kaspersky Lab virus analysts work around the clock. Every day they uncover hundreds of thousands of new computer threats, create tools to detect and disinfect them, and include their signatures in databases used by Kaspersky Lab applications.
Technologies. Many technologies that are now part and parcel of modern anti-virus tools were originally developed by Kaspersky Lab. It is no coincidence that many other developers use the Kaspersky Anti-Virus engine in their products, including: Alcatel-Lucent, Alt-N, Asus, BAE Systems, Blue Coat, Check Point, Cisco Meraki, Clearswift, D-Link, Facebook, General Dynamics, H3C, Juniper Networks, Lenovo, Microsoft, NETGEAR, Openwave Messaging, Parallels, Qualcomm, Samsung, Stormshield, Toshiba, Trustwave, Vertu, and ZyXEL. Many of the company’s innovative technologies are patented.
Achievements. Over the years, Kaspersky Lab has won hundreds of awards for its services in combating computer threats. Following tests and research conducted by the reputed Austrian test laboratory AV-Comparatives in 2014, Kaspersky Lab ranked among the top two vendors by the number of Advanced+ certificates earned and was ultimately awarded the Top Rated certificate. But Kaspersky Lab's main achievement is the loyalty of its users worldwide. The company’s products and technologies protect more than 400 million users, and its corporate clients number more than 270,000.
Kaspersky Lab website: |
|
Virus encyclopedia: |
|
Kaspersky VirusDesk: |
https://virusdesk.kaspersky.com (for analyzing suspicious files and websites) |
Kaspersky Lab Community: |
Page top
Information about third-party code
Information about third-party code is contained in the file legal_notices.txt, in the application installation folder.
Page top
Trademark notices
This chapter lists the owners of third-party trademarks that are used in this document.
Registered trademarks and service marks are the property of their respective owners.
AppleTalk is a trademark of Apple Inc., registered in the U.S. and other countries.
Google is a trademark of Google, Inc.
Windows is a registered trademark of Microsoft Corporation in the United States and other countries.
IPX is a registered trademark of Novell Inc. in the United States and other countries.
Python is a trademark or registered trademark of the Python Software Foundation.
UNIX is a registered trademark in the United States and other countries, licensed exclusively through X/Open Company Limited.
Page top