Kaspersky Industrial CyberSecurity for Networks API Developer's Guide
2.9 API

Contents

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

In this section

Getting Kaspersky Security Center agent configuration

Getting Kaspersky Industrial CyberSecurity for Networks configuration

Getting Kaspersky Industrial CyberSecurity for Networks version

Getting dictionary values
Page top
[Topic 152315]

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:

  • GetKscConfiguration

    Returns 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)

Page top
[Topic 152316]

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:

  • GetConfigurationMetadata

    Returns 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.

  • GetPlcConfiguration

    Returns a list of PLCs and information about them, such as hash identifier, name, and type of PLC, and a list of protocols.

  • GetProtocolConfiguration

    Returns configuration for protocols of the specified PLC. This information includes protocol identifier, name, type, monitoring point name, device address, and transport address.

  • GetTagsForPlc

    Returns 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.

  • GetTagsForProtocol

    Returns 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.

  • GetEventDescriptors

    Returns 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)

Page top
[Topic 152320]

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:

  • GetVersion

    Returns 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)

Page top
[Topic 154549]

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:

  • GetDictionary

    Returns 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)

Page top
[Topic 152325]