Using Kaspersky Security for Virtualization 6.2 Light Agent in multitenancy mode

When using Kaspersky Security in multitenancy mode, a single instance of Kaspersky Security installed in the infrastructure of the cybersecurity service provider (hereinafter also referred to as the "service provider") allows protection of isolated virtual infrastructures of tenant organizations or isolated units of one tenant organization (hereinafter also referred to as "tenants").

The procedures for deploying and using Kaspersky Security in multitenancy mode are automated using the Integration Server REST API.

The following Kaspersky Security multitenancy usage scenarios are supported:

• Deploying a tenant protection infrastructure using the Integration Server REST API via virtual Kaspersky Security Center Administration Servers and receiving tenant protection reports.
• Receiving tenant protection reports without deploying tenant protection infrastructure using the Integration Server REST API.

  If the tenant protection infrastructure is already deployed in your infrastructure without using the Integration Server REST API, you can register existing tenants and their virtual machines and receive tenant protection reports.

Deploying a tenant protection infrastructure

The tenant protection infrastructure created using the Integration Server REST API is based on the use of virtual Kaspersky Security Center Administration Servers. Each tenant is provided with a virtual Administration Server and an account that the tenant administrator uses to connect to the virtual Administration Server.

One Kaspersky Security Center Administration Server can support up to 500 virtual Administration Servers.

Tenant virtual machines with Light Agents installed are located on the tenant's virtual Administration Server.

A tenant administrator can perform the following actions on their virtual Administration Server:

• Centrally manage protection of their virtual machines using the Light Agent policies and group tasks.
• Receive information about their infrastructure protection status using event notifications and reports available on the virtual Administration Server.
• Work with copies of files placed in backup storage on all of the virtual machines of this tenant.

For more information about virtual Administration Servers, see the Kaspersky Security Center help.

The service provider's administrator installs the solution in their infrastructure and ensures the operation of Light Agents and other solution components:

• Configures the settings for connecting Light Agents installed on tenant virtual machines to the SVMs and to the Integration Server.
• Activates the solution and monitors license restrictions.
• Updates the solution's databases and application modules.
• Configures the Protection Server settings.

The service provider's administrator can also configure general protection settings for tenant virtual machines.

During operation, information that may contain personal and confidential data is transmitted between Kaspersky Security Center and Kaspersky Security solution components installed in the service provider's infrastructure and on tenant virtual machines.

Before creating a tenant protection infrastructure, you need to perform the following steps:

1. Install or update the Kaspersky Security solution.

   The following components must be installed in the service provider's infrastructure:

   • Integration Server and Integration Server Console.
   • Protection Server.
   • Kaspersky Security management plug-ins.
2. Prepare the solution for work:
   • Prepare the Protection Server for operation.
   • Change the default password of the multitenancy account. A multitenancy account is created automatically as a result of Integration Server installation. It is required to interact with the Integration Server REST API.
   • Configure the settings for connecting the Integration Server to Kaspersky Security Center Administration Server. These settings are required for authorization on the Kaspersky Security Center Administration Server when executing requests to the Integration Server REST API.

Deploying a tenant protection infrastructure consists of the following steps:

1. Creating a tenant and virtual Kaspersky Security Center Administration Server for the tenant.
2. Configuring the location of SVMs that will protect tenants' virtual machines and configuring Protection Server settings.
3. Configuring SVM discovery settings and general operating settings for Light Agents installed on tenant virtual machines.
4. Installing Kaspersky Security Center Network Agent and Light Agent on tenant virtual machines and moving the virtual machines to a virtual Administration Server configured for the tenant.
5. Registering tenant virtual machines in the Integration Server database.
6. Activating a tenant.
7. Transferring the following Kaspersky Security Center Administration Server connection settings to the tenant administrator:
   • Address of the virtual Administration Server configured for the tenant;
   • Administrator account settings of the virtual Administration Server.

   Tenant administrator are advised to change the account password they receive from the service provider's administrator.

The steps of deploying tenant protection infrastructure can be automated using the Integration Server REST API and the Kaspersky Security Center OpenAPI (open the description of Kaspersky Security Center OpenAPI methods).

To prevent unauthorized access, it is recommended to deploy the SVM and the device on which the Kaspersky Security Center Administration Server and the Integration Server are installed in a dedicated virtual network and to configure routing with address translation (SNAT) from the tenant subnets to this subnet.

Configuring the Integration Server connection settings to the Kaspersky Security Center Administration Server

For the Integration Server REST API interaction with the Kaspersky Security Center Administration Server during execution of requests, an account is required that has the following permissions in the Kaspersky Security Center:

• Permissions in the functional areas of the Administration Server:
  • General functionality → Basic functionality: Read, Modify
  • General functionality → Administration group management: Modify
  • General functionality → User permissions: Modify access control lists
  • General functionality → Virtual Administration Servers: Read, Modify, Execute, Manage
• Permissions to read and modify objects in the functional areas related to Light Agent settings.

You can create and configure an account to connect the Integration Server to Kaspersky Security Center:

• In Kaspersky Security Center Administration Console, in the Security section of the Kaspersky Security Center Administration Server properties window.

  By default, the Security section is not displayed in the Administration Server properties window. To enable the display of the Security section, you must select the Display security settings sections check box in the Configure interface window (View → Configure interface menu) and restart the Kaspersky Security Center Administration Console.

• In Kaspersky Security Center Web Console, in the Users and roles → Users and groups section of the main window.

For more information on creating and configuring account rights in Kaspersky Security Center, see the Kaspersky Security Center Help.

How to configure the Integration Server's connection to Kaspersky Security Center Administration Server in Integration Server Web Console

How to configure the Integration Server's connection to Kaspersky Security Center Administration Server in Integration Server Console

Creating a tenant and virtual Administration Server

At this step of the deployment of tenant protection infrastructure, tenant information is added to the Integration Server database and a virtual Administration Server is created for the tenant. The procedures are automated by means of the Integration Server REST API.

The actions performed in response to the REST API request depend on the tenant type specified when calling the REST API method: deployment of tenant protection infrastructure is available only for the complete tenant type.

Specify the following information in the REST API request:

• Tenant name.
• Tenant type: complete.
• Settings of the account used by the tenant administrator to connect to the virtual Administration Server configured for the tenant. During the procedure, an account with the main administrator permissions will be automatically created on the virtual Administration Server.

  Kaspersky Security Center verifies the uniqueness of account names within the main Kaspersky Security Center Administration Server and all its virtual Administration Servers. By default, if the account name is not unique, the account creation fails. If you want to use same account names for the virtual Administration Servers, you can disable uniqueness check for internal user names. See Kaspersky Security Center help for more information.

As a result of the procedure, the following actions are performed:

• Tenant data is saved in the Integration Server database, and the tenant is assigned a unique identifier.
• A virtual Kaspersky Security Center Administration Server and an account used by the tenant administrator to connect to the virtual Administration Server are created for each tenant.
• When registering the first tenant on the main Administration Server, a folder with the default name Multitenancy KSV LA is created in the Managed devices folder. You can change this name if required.
• The following structure of folders and nodes is created for each tenant in the Multitenancy KSV LA folder:

  <Tenant name> folder

  • Administration Servers node
    • Administration Servers <Tenant name> node
      • Folders and administration groups required for managing protection of this tenant, similar to the structure of folders and groups of the main Kaspersky Security Center Administration Server.

Configuring SVM location and Protection Server settings

At this step of the deployment of tenant security infrastructure, you can perform the following actions:

1. Configure the location of SVMs that will protect tenant virtual machines in the Kaspersky Security Center administration group hierarchy.
2. Configure the operation settings of the Protection Server installed on these SVMs using the Protection Server policy.
3. Configure the general settings of the Light Agents that will be installed on tenant virtual machines using Light Agent policies.

You can deploy SVMs that will protect tenant virtual machines in any folder or administration group on the main Kaspersky Security Center Administration Server.

It is not recommended to deploy the SVMs and Protection Server policy in folders and administration groups to which the tenant administrator has access, that is, in folders and administration groups under the Administration Server <Tenant name> node.

If you want the SVM to protect virtual machines of only particular tenants, you need to restrict Light Agents' access to the SVM in one of the following ways:

• Using the connection tags mechanism. Tags must be specified in the Protection Server policy and in the Light Agent policy. It is recommended to "lock" the configured settings in order to prevent these settings from being changed in child policies.
• By blocking network connections from the tenant subnet to the subnet with the SVM on TCP ports 80, 9876, 9877, 11111, and 11112.

It is not recommended to configure connection tags in Light Agent policies located in folders and administration groups to which the tenant administrator has access, that is, in folders and administration groups under the Administration Server <Tenant name> node.

In accordance with the procedure for inheritance of Kaspersky Security Center policies, the default Protection Server policy is applied on all SVMs in administration group hierarchy. It is created in the Managed devices folder on the main Administration Server. If you want to configure specific operating settings for the SVMs that will protect tenant virtual machines, you need to create a Protection Server policy in the folder where the SVM that protects tenant virtual machines is located.

If you want to centrally enable use of Kaspersky Security Network to protect tenants' virtual machines, make sure that tenants' personal data is being processed legally.

Configuring settings for SVM discovery by Light Agents and general tenant protection settings

At this stage of deployment of the tenant protection infrastructure, you need to create a Light Agent policy in one of the following folders:

• In the Multitenancy KSV LA → <Tenant name> folder, if you want to configure general operating settings for all Light Agents that will be installed on the virtual machines of one particular tenant. A policy in the Multitenancy KSV LA → <Tenant name> folder must be created for each tenant.
• In the Multitenancy KSV LA folder, if you want to configure general operating settings for all Light Agents that will be installed on the virtual machines of all tenants.

In the Light Agent policy, configure the Light Agent operation settings as follows:

• Settings for connecting Light Agents to SVMs:
  • Enable the use of the Integration Server for SVM discovery in the Light Agent policy. Light Agents installed on the virtual machines of complete tenants must use the Integration Server to discover SVMs that are available for connection.
  • If you want to restrict Light Agents access to SVMs using the mechanism of connection tags, you can assign connection tags to Light Agents.

    To restrict Light Agents' access to SVMs, you can also block network connections from the tenant subnet to the subnet with the SVM on TCP ports 80, 9876, 9877, 11111, and 11112.

  The default values can be used for other settings for connecting Light Agents to SVMs.

  It is recommended to "lock" all the settings for connecting Light Agents to SVMs in order to prevent these settings from being changed in child policies.

• If required, you can configure general operating settings for the Light Agents that will be installed on the tenant virtual machines.

  You can use the "lock" attribute to allow or block changing of settings or groups of settings in task settings or in nested policies (for nested administration groups and secondary Administration Servers). Tenant administrators cannot configure "locked" settings. If the "locks" are open, the tenant administrator can independently configure the operation of Light Agent components.

It is not recommended to configure the general operating settings of Light Agents in the policies located in folders and administration groups to which the tenant administrator has access, that is, in folders and administration groups under the Administration Server <Tenant name> node.

Installing a Light Agent on tenant virtual machines

At this step of the deployment of the tenant security infrastructure, the following actions are performed:

• Kaspersky Security Center Network Agent, which is configured to connect to the tenant's virtual Administration Server, is installed on tenant virtual machines.
• Tenant virtual machines are moved to the Managed devices folder of the virtual Administration Server configured for the tenant.
• Light Agent for Linux or Light Agent for Windows is installed on tenant virtual machines.

The listed actions can be performed both on the service provider's side and on the tenant's side after the tenant administrator receives the virtual Administration Server connection settings.

If installation is performed on the service provider's side

You can use the following installation methods:

• Using Kaspersky Security Center OpenAPI, automate the installation of applications on tenant virtual machines and the movement of virtual machines to administration groups (open a description of Kaspersky Security Center OpenAPI methods).
• Remotely install applications on virtual machines using the Kaspersky Security Center wizard or remote installation task.
• Deploy virtual machines from a virtual machine template.

  If you want to use Kaspersky Security Center OpenAPI or Kaspersky Security Center remote installation tools, then for each tenant you need to prepare the installation packages required to install Light Agent and Kaspersky Security Center Network Agent. You can distribute installation packages to the selected virtual Administration Servers using the Administration Server task or automate the distribution of packages using Kaspersky Security Center OpenAPI (open the description of Kaspersky Security Center OpenAPI methods).

  In the package properties or in the properties of the remote installation task, you can specify the administration group that the virtual machine should be assigned to after Network Agent is installed on it. For more information about configuring installation packages and the deployment procedure, see the Kaspersky Security Center Help.

  If you want to deploy virtual machines from a virtual machine template, then for each tenant you need to prepare a virtual machine template that has an installed Network Agent configured to connect to the tenant's virtual Administration Server and an installed Light Agent. Then you can deploy virtual machines for the tenant from this template.

  When installing Network Agent on a virtual machine template, it is recommended to enable optimization of Network Agent settings for VDI.

If installation is performed on the tenant's side

If there are installation packages or virtual machine templates prepared by the service provider's administrator, the tenant's administrator can install Network Agent and Light Agent on the tenant virtual machines.

Registering tenant virtual machines

At this step of the deployment of the tenant security infrastructure, tenant virtual machines are registered. The procedure is automated by means of the Integration Server REST API.

In the request to the REST API, you need to specify the virtual machine ID (BIOS ID) and the tenant ID of the tenant to which these virtual machines belong.

As a result of performing the procedure, information about the virtual machine is saved in the Integration Server database and a connection is established between the virtual machine and the tenant.

Activating a tenant

The tenant activation procedure is performed at this stage of deploying the tenant security structure. Tenants are registered with the "Inactive" status in the Integration Server database. As long as the tenant has this status, Light Agents installed on the tenant virtual machines do not receive information about the SVMs they can connect to, and protection of the tenant virtual machines is disabled. To start protecting tenant virtual machines, you must activate the tenant.

The tenant activation procedure is automated using the Integration Server REST API.

As a result of the procedure, the following actions are performed:

• The tenant status changes to "Active". The tenant status is saved in the Integration Server database. You can get information about the tenant status using the Integration Server REST API or by viewing the list of tenants in the Integration Server Console.
• The Light agents installed on the tenant virtual machines receive information about the SVMs available for connection from the Integration Server. The Light Agents select the best SVMs for connection in accordance with the configured SVM connection settings, and protection of the tenant virtual machines is enabled.

Registering existing tenants and their virtual machines

If the tenant protection infrastructure is configured without the use of the Integration Server REST API, you need to add information about the tenants and their virtual machines to the Integration Server database in order to generate tenant protection reports.

Registration of an existing tenant and its virtual machines in the Integration Server database consists of the following steps:

1. Creating a tenant in the Integration Server database.

   The tenant creation procedure is automated using the Integration Server REST API.

   The actions performed in response to the REST API request depend on the tenant type specified when calling the REST API method. To enter the tenant data into the Integration Server database without creating a tenant protection infrastructure, specify the simple tenant type.

   Specify the following information in the REST API request:

   • Tenant name.
   • Tenant type: simple.

   As a result, the tenant data is saved in the Integration Server database and the tenant is assigned an identifier.

2. Registering tenant virtual machines in the Integration Server database.

   The virtual machine registration procedure is automated by means of the Integration Server REST API.

   In the request to the REST API, specify the identifier (BIOS ID) of each virtual machine and the tenant ID of the tenant to which these virtual machines belong.

   As a result, the data on the tenant virtual machines is saved in the Integration Server database.

3. Activating a tenant.

   The tenant activation procedure is automated using the Integration Server REST API.

   After activation, the tenant status is saved in the Integration Server database. You can get information about the tenant status using the Integration Server REST API or by viewing the list of tenants in the Integration Server Console.

   For a simple tenant, its status ("Active" or "Inactive") does not affect the protection state of tenant virtual machines.

Enabling and disabling tenant protection

Tenants registered in the Integration Server database may have the "Active" or "Inactive" status. By default, the tenant status is "Inactive".

For a complete tenant, the tenant status determines the protection status of tenant virtual machines:

• If the tenant status is "Active", the Integration Server sends Light Agents installed on the tenant virtual machines the list of SVMs available for connection. The Light Agents select the best SVM for connection in accordance with the configured SVM connection settings and connect to it. Protection of the tenant virtual machines is enabled.
• If the tenant status is "Inactive", the Integration Server sends Light Agents installed on the tenant virtual machines the address of a non-existent SVM. This means that Light Agents are not able to connect to any SVM. Protection of the tenant virtual machines is disabled.

To enable protection of the virtual machines for a complete tenant, you must activate the tenant. If you want to disable protection of the virtual machines for a complete tenant (stop providing protection services to the tenant), you can deactivate the tenant.

After the tenant is deactivated, events from the Light Agents installed on the tenant virtual machines are logged to the Kaspersky Security Center Administration Server. An event that there are no SVMs available for connection is logged once, and events indicating that the update task could not be run on the protected virtual machine are logged every 2 hours.

To avoid unauthorized use of the application, after a tenant is deactivated, it is recommended to block network connections from the deactivated tenant's subnet to the following TCP ports of the SVM subnet: 80, 9876, 9877, 11111, 11112.

For a simple tenant, the status does not affect the virtual machine protection status.

The tenant activation and deactivation procedures are automated using the Integration Server REST API.

Getting information about tenants

Kaspersky Security implements the following methods for getting information about tenants:

• View the list of tenants in Integration Server Web Console or in Integration Server Console
• Get the list of tenants, list of tenant virtual machines and tenant information using the Integration Server REST API

How to view tenant information in Integration Server Web Console

How to view tenant information in Integration Server Console

Getting tenant protection reports

A virtual machine is considered protected if the Light Agent installed on it is connected to the SVM. Each SVM can receive data about the time intervals when Light Agents were connected to the SVM and pass this data to the Integration Server database. Based on this information, you can use the Integration Server REST API to receive reports on the protection status of the tenant virtual machines.

You can use the tenant protection report to get information about all protected tenant virtual machines and all time intervals when each virtual machine was protected by Kaspersky Security. The report can also be used to get information about the protection of all virtual machines that connected to the SVM during the specified reporting period, including the virtual machines that do not belong to any tenant.

Getting tenant protection reports consists of the following steps:

1. Enabling the function of transferring report data to the Integration Server database.
2. Report generation. The report is generated as a CSV file in a temporary folder.
3. Report upload. The generated report can be uploaded in its entirety or in parts for integration into the service provider's reporting system.

Enabling the function of transferring report data

By default, the function of transferring report data is disabled on the Integration Server. If you want to receive tenant protection reports, you need to enable the reporting data feature in the Integration Server configuration file appsettings.json. Depending on the version of the Integration Server, the file is located at one of the following paths:

• /var/opt/kaspersky/viis/common/ for the Linux-based Integration Server
• %ProgramFiles(x86)%\Kaspersky Lab\Kaspersky VIISLA\ for the Windows-based Integration Server.

To enable the function of receiving report data:

1. Open the appsettings.json configuration file for editing.
2. In the Multitenancy section, set the EnableProtectionReports parameter to true and save the file.
3. Restart the Integration Server.

The Integration Server will receive data on the time intervals when Light Agents were connected to SVMs from each SVM.

If the function of receiving report data is enabled, but SVM is not connected to the Integration Server, the data packets are queued for sending. When the maximum number of packets in the queue is reached, older data packets are deleted. The parameters for sending data are set up in the /etc/opt/kaspersky/agents_monitor/agents_monitor.conf configuration file on SVM. You can configure the maximum queue size for the packets to be sent using the max_queue_size parameter.

The received data is stored in the Integration Server database. The default report retention period is 460 days. You can specify this value using the ProtectionPeriodsRecordsLifetimeDays parameter in the Multitenancy section of the appsettings.json configuration file of the Integration Server.

The size of the Integration Server database increases in proportion to the number of the protected tenant virtual machines.

Page top

Generating tenant protection reports

The report generation procedure is automated by means of the Integration Server REST API.

You can pass the following report generation parameters in the request to the REST API:

• Identifier of the tenant for which you want to generate the report.
• Start date and time of the period for which you want to generate a report.
• End date and time of the period for which you want to generate a report.

If a tenant ID is not specified in the request, the report will include data on all virtual machines that were protected during the specified period, data on virtual machines that do not belong to tenants.

If the report generation period is not specified in the request, the report will include data stored in the Integration Server database from the earliest date up to the current moment.

To obtain reliable information in the reports, it is recommended to follow these rules when specifying the reporting period:

• Specify the reporting period accurate to a day.
• Set the end of the reporting period not less than 60 minutes from the current moment.

As a result of the report generation procedure, the report identifier is returned. Depending on the version of the Integration Server, the report is saved at the following path:

• /var/opt/kaspersky/viis/common/reports – protected directory of the Linux-based Integration Server.
• %ProgramData%\Kaspersky Lab\VIISLA\protectionPeriodsReports – protected folder of the Linux-based Integration Server.

By default, the report is stored for 24 hours from the moment of generation. To get the report, use the report identifier in the request to the REST API to upload the report.

You can configure the report retention period using the ProtectionPeriodsRecordsLifetimeDays parameter in the Multitenancy section of the appsettings.json configuration file of the Integration Server. Depending on the version of the Integration Server, the file is located at one of the following paths:

• /var/opt/kaspersky/viis/common/ for the Linux-based Integration Server
• %ProgramFiles(x86)%\Kaspersky Lab\Kaspersky VIISLA\ for the Windows-based Integration Server.

The data in the report is presented line by line. Each line contains information about one virtual machine protection period in the following format:

{tenant ID};{tenant name};{virtual machine ID};{virtual machine name};{date and time when protection was enabled};{date and time when protection was disabled}

where:

• {tenant ID} – identifier of the tenant to which the virtual machine belongs. If the virtual machine does not belong to any tenant, nothing is displayed in this field.
• {tenant name} – tenant name specified when creating the tenant. If the virtual machine does not belong to any tenant, nothing is displayed in this field.
• {virtual machine ID} – identifier of the virtual machine that was protected by the application.
• {virtual machine name} – name of the virtual machine that was protected by the application.
• {date and time when protection was enabled} – start date and time of the virtual machine protection period.
• {date and time when protection was disabled} – end date and time of the virtual machine protection period.

If during the reporting period the virtual machine was protected by the application several times (protection was enabled and disabled), the report displays each virtual machine protection period.

Uploading tenant protection reports

The report upload procedure is automated by means of the Integration Server REST API.

In the request to the REST API, the report identifier obtained at the previous step and the data display format (CSV) must be specified.

Other data display formats are not supported.

You can upload all report data or get partial data.

You can integrate data obtained as a result of the query into your reporting system.

Removing virtual machines from the protected infrastructure

To remove a virtual machine from the protected infrastructure of a complete tenant:

1. Unregister the virtual machine in the Integration Server database. The virtual machine unregistration procedure is automated by means of the Integration Server REST API.

   As a result, information about the tenant virtual machine is deleted from the Integration Server database.

2. On the virtual machine, uninstall Kaspersky Security Center Network Agent, Light Agent for Linux, or Light Agent for Windows.

   You can perform these actions manually in the Kaspersky Security Center interface or automate the removal using Kaspersky Security Center OpenAPI (open a description of Kaspersky Security Center OpenAPI methods).

3. Remove the virtual machine from the list of the tenant's managed devices. You can move the virtual machine to the Unassigned devices folder of Kaspersky Security Center main Administration Server or delete the virtual machine from Kaspersky Security Center.

   You can perform these actions manually in Kaspersky Security Center interface or automate virtual machine removal form the list of managed devices using Kaspersky Security Center OpenAPI (open the description of Kaspersky Security Center OpenAPI methods).

If the virtual machine is removed from the protected infrastructure of a simple tenant, you need to unregister the virtual machine in the Integration Server database.

Removing tenants

If you want to stop providing services to a complete tenant, you need to remove the tenant. To do so, perform the following actions:

1. On the virtual machine, uninstall Kaspersky Security Center Network Agent, Light Agent for Linux, or Light Agent for Windows.

   You can perform these actions manually in the Kaspersky Security Center interface or automate the removal using Kaspersky Security Center OpenAPI (open a description of Kaspersky Security Center OpenAPI methods).

2. Remove the tenant from the Integration Server database, and remove the tenant protection infrastructure. The removal procedure is automated by means of the Integration Server REST API. When calling the REST API method, specify the removeTenantArtifacts=true parameter.

   As a result of the procedure, the following actions are automatically performed:

   • Information about the tenant and the tenant virtual machines is deleted from the Integration Server database.
   • The tenant protection infrastructure is removed from Kaspersky Security Center, namely: virtual Administration Server and the account for connecting to it, the Multitenancy KSV LA → <Tenant name> folder and its contents (subfolders and administration groups, policies and tasks, and installation packages).
   • If there are no other tenants, the Multitenancy KSV LA folder is also deleted.

If protection services are terminated for a simple tenant, you need to remove the tenant from the Integration Server database.

Using the Integration Server REST API in multi-tenancy scenarios

Interaction with the Integration Server REST API is based on requests and responses and is carried out over the HTTPS protocol using the multitenancy account.

Account parameters are passed as the following string {username}:{password} at every method call in the Authorization request header and are encoded with the Base64 method. Authentication of the Basic type is used.

The address of the request to the Integration Server REST API consists of the following parts:

https://{Integration Server address}:{Integration Server port}/{method}?{parameters}

where:

• {Integration Server address} – IP address or fully qualified domain name (FQDN) of the Integration Server.
• {Integration Server port} – port for connecting to the Integration Server (port 7271 by default).
• {method} – method to call.
• {parameters} – method parameters, if any.

For processing requests that are time consuming and run asynchronously, tasks are used. The task is created as an intermediate query result.

Methods for working with tenants

Using the Integration Server REST API, you can perform the following actions when working with tenants and tenant virtual machines:

• Get information about a tenant
• Get a list of tenants
• Get a list of tenant virtual machines
• Create a new tenant and its protection infrastructure, or register an existing tenant
• remove a tenant
• activate and deactivate a tenant
• register and unregister tenant virtual machines

The set of actions performed as a result of some REST API requests depends on the tenant type that you specify when adding the tenant information to the Integration Server database. Deployment and deletion of the tenant protection infrastructure using the Integration Server REST API is available for complete tenants. For a simple tenant, only report generation is automated.

Getting information about a tenant

Allows you to get information about the tenant from the Integration Server database.

Method:

GET /api/2.0/virtualization/tenants/{tenant ID}

where:

{tenant ID} – tenant identifier in the Integration Server database (required parameter).

In case of successful completion of the request, the REST API returns the following information about the tenant:

<tenant id="{ID}" created="{date and time}" updated="{date and time}">

<name>{name}</name>

<description>{description}</description>

<userData><![CDATA[{additional information}]]></userData>

<!-- Information in the vKsc section is available only for a complete tenant -->

<vKsc id="{ID}">

<user>

<name>{administrator}</name>

</user>

</vKsc>

<status>{status}</status>

<type>{tenant type}</type>

</tenant>

where:

• tenant id="{ID}" – tenant identifier in the Integration Server database.
• created="{date and time}" – date and time when the tenant was registered in the Integration Server database, in YYYY-MM-DDThh:mm:ss format.
• updated="{date and time}" – date and time when the tenant data was updated in the Integration Server database, in YYYY-MM-DDThh:mm:ss format.
• {name} – tenant name specified when the tenant was created.
• {description} – tenant description.
• {additional information} – additional tenant information added to the Integration Server database.
• vKsc id="{ID}" – identifier assigned to the tenant's virtual Administration Server in Kaspersky Security Center.
• {administrator} – name of the administrator of the tenant's virtual Administration Server.
• {status} – current tenant status: Active or Inactive.
• {tenant type} – type of tenant: Complete or Simple.

Return codes:

• 200 (OK) – request completed successfully. The tenant information is returned in the response.
• 403 (Forbidden) – access to the resource is denied.
• 404 (Not Found) VIRMT_TenantWithSpecifiedIdNotFound – a tenant with the specified identifier is not found in the Integration Server database.

Getting a tenant list

Allows you to get a list of all tenants whose information is stored in the Integration Server database, as well as information about each tenant.

Method:

GET /api/2.0/virtualization/tenants

Return codes:

• 200 (OK) – request completed successfully. A list of information about all tenants is returned in the response.
• 403 (Forbidden) – access to the resource is denied.

Getting a list of tenant virtual machines

Allows you to get a list of all registered tenant virtual machines.

Method:

GET /api/2.0/virtualization/tenants/{tenant ID}/vms

where:

{tenant ID} – tenant identifier in the Integration Server database (required parameter).

If the request succeeds, the REST API returns a list of virtual machines and the following information about each tenant virtual machine:

<vm id="{ID in the database}" biosId={BIOS ID} created="{date and time}" updated="{date and time}">

<name>{name}</name>

<userData><![CDATA[{additional information}]]></userData>

</vm>

where:

• {ID in the database} – identifier assigned to the virtual machine in the Integration Server database.
• {BIOS ID} – virtual machine identifier (BIOS ID) in UUID format.
• created="{date and time}" – date and time when the virtual machine was registered in the Integration Server database in YYYY-MM-DDThh:mm:ss format.
• updated="{date and time}" – date and time when the virtual machine data was updated in the Integration Server database in YYYY-MM-DDThh:mm:ss format.
• {name} – virtual machine name.
• {additional information} – additional information about the virtual machine stored in the Integration Server database.

Return codes:

• 200 (OK) – request completed successfully. A list of the tenant virtual machines is returned in the response.
• 403 (Forbidden) – access to the resource is denied.
• 404 (Not Found) VIRMT_TenantWithSpecifiedIdNotFound – a tenant with the specified identifier is not found in the Integration Server database.

Creating a tenant

Depending on the tenant type that you specify when calling the REST API method, the following actions can be performed:

• For a complete tenant:
  • Add tenant data to the Integration Server database.
  • Create the tenant protection infrastructure in Kaspersky Security Center (virtual Administration Server, account for connecting to it, structure of folders and administration groups).
  • Add information about the tenant's virtual Administration Server to the Integration Server database.
• For a simple tenant: add the tenant data to the Integration Server database.

Method:

POST /api/2.0/virtualization/tenants

The following parameters must be specified in the request body:

<tenant>

<name>{name}</name>

<description>{description}</description>

<userData><![CDATA[{additional information}]]></userData>

<preferredViisAddress>{IP address}</preferredViisAddress>

<type>{tenant type}</type>

<!-- Data in the vKsc section is specified only for a complete tenant -->

<vKsc>

<user>

<name>{administrator name}</name>

<password>{administrator password}</password>

</user>

</vKsc>

</tenant>

where:

• {name} – tenant name (required parameter).
• {description} – tenant description (optional parameter).
• {additional information} – additional tenant information (optional parameter).
• {IP address} – IP address of the Integration Server to which the Light Agents installed on tenant virtual machines will connect (optional parameter). The specified address is used by default when creating the Light Agent policy. If the parameter is not specified, the policy uses the Integration Server IP address from the request to REST API.
• {tenant type} – type of tenant: Complete or Simple (optional parameter).
• {administrator name} – name of the administrator account used to connect to the tenant's virtual Administration Server (required when creating a complete tenant). The account will be created automatically during the procedure.
• {administrator password} – Base64-encoded password for the administrator account (required when creating a complete tenant).

The request is executed asynchronously, REST API returns identifier of the CreateTenant task. Using the task, you can monitor the progress of the tenant creation procedure. When the task completes, the result field displays information about the tenant including the identifier of the created tenant, or an error message. In case of an error at any step of the procedure, all the changes are rolled back.

Return codes:

• 202 (Accepted) – the request is accepted for execution. The response returns the identifier of the CreateTenant task.
• 400 (Bad request) VIRMT_MandatoryParameterIsNotSpecified – one of the required parameters, for example, the tenant name, is not specified in the request body.
• 400 (Bad request) VIRMT_InvalidTenantType – an invalid tenant type is specified in the request body; the specified tenant type does not exist.
• 400 (Bad request) VIRMT_VKscCredentialsNotSpecified – the name or password of the administrator account of the virtual Kaspersky Security Center Administration Server is not specified (when creating a complete tenant).
• 400 (Bad request) VIRMT_InvalidViisAddressFormat – invalid format of the Integration Server IP address.
• 403 (Forbidden) – access to the resource is denied.

Possible error codes in the task:

• KSC_ServiceNotConfigured – Kaspersky Security Center connection settings are not specified.
• VIRMT_TenantGroupAlreadyExists – a folder whose name corresponds to the specified tenant name already exists in Kaspersky Security Center.
• VIRMT_TenantWithSpecifiedNameAlreadyExists – a tenant with the specified name already exists in the Integration Server database.
• VIRMT_PasswordNotComplyPolicy – failed to create an administrator account for Kaspersky Security Center virtual Administration Server: the specified password does not meet Kaspersky Security Center password requirements.
• VIRMT_UserWithSpecifiedNameAlreadyExists – failed to create an administrator account for Kaspersky Security Center virtual Administration Server: a user with the specified name already exists in Kaspersky Security Center.

Activating a tenant

Allows changing the tenant status to "Active".

Method:

POST /api/2.0/virtualization/tenants/{tenant ID}/activate

where:

{tenant ID} – tenant identifier in the Integration Server database (required parameter).

The request is executed asynchronously, REST API returns identifier of the ChangeTenantActivation task. Using the task, you can monitor the progress of the procedure for changing the tenant status. When the task is done, the result field displays confirmation that the tenant status changed (true) or an error message.

Return codes:

• 202 (Accepted) – the request is accepted for execution. The response returns the identifier of the ChangeTenantActivation task.
• 403 (Forbidden) – access to the resource is denied.

Error codes in the task:

• VIRMT_TenantWithSpecifiedIdNotFound – a tenant with the specified identifier is not found in the Integration Server database.
• KSC_ServiceNotConfigured – Kaspersky Security Center connection settings are not specified.

Deactivating a tenant

Allows changing the tenant status to "Inactive".

Method:

POST /api/2.0/virtualization/tenants/{tenant ID}/deactivate

where:

{tenant ID} – tenant identifier in the Integration Server database (required parameter).

The request is executed asynchronously, REST API returns identifier of the ChangeTenantActivation task. Using the task, you can monitor the progress of the procedure for changing the tenant status. When the task is done, the result field displays confirmation that the tenant status changed (true) or an error message.

Return codes:

• 202 (Accepted) – the request is accepted for execution. The response returns the identifier of the ChangeTenantActivation task.
• 403 (Forbidden) – access to the resource is denied.

Error codes in the task:

• VIRMT_TenantWithSpecifiedIdNotFound – a tenant with the specified identifier is not found in the Integration Server database.
• KSC_ServiceNotConfigured – Kaspersky Security Center connection settings are not specified.

Registering tenant virtual machines

Allows you to add information about the tenant virtual machines to the Integration Server database.

Method:

POST /api/2.0/virtualization/tenants/{tenant ID}/vms/register

where:

{tenant ID} – tenant identifier in the Integration Server database (required parameter).

The following parameters must be specified In the request body:

<vm biosId="{BIOS ID}">

<name>{name}</name>

<userData><![CDATA[{additional information}]]></userData>

</vm>

where:

• {BIOS ID} – unique virtual machine identifier (BIOS ID) (required parameter).
• {name} – virtual machine name (optional parameter).
• {additional information} – additional information about the virtual machine (optional parameter).

Return codes:

• 200 (OK) – request completed successfully (information about the virtual machine is added to the Integration Server database).
• 403 (Forbidden) – access to the resource is denied.
• 404 (Not Found) VIRMT_TenantWithSpecifiedIdNotFound – a tenant with the specified identifier is not found in the Integration Server database.
• 409 (Conflict) VIRMT_VmWithSpecifiedBiosIdAlreadyExists – virtual machine with the specified identifier is already registered in the Integration Server database.

Unregistering a virtual machine

Allows you to delete information about the tenant virtual machine from the Integration Server database.

Unregistration does not disable protection of the tenant virtual machine. You can disable protection of the virtual machine for a complete tenant by following all the steps of the procedure for removing virtual machines from the protected infrastructure.

Method:

POST /api/2.0/virtualization/tenants/{tenant ID}/vms/unregister?biosId={ID}

or

POST /api/2.0/virtualization/tenants/{tenant ID}/vms/unregister?vmId={ID}

where:

• {tenant ID} – tenant identifier in the Integration Server database (required parameter).
• biosId={ID} – virtual machine identifier (BIOS ID) in UUID format (required parameter).
• vmId={ID} – identifier of the virtual machine in the Integration Server database, in the UUID format (required parameter).

Return codes:

• 200 (OK) – request completed successfully (information about the virtual machine is deleted from the Integration Server database).
• 403 (Forbidden) – access to the resource is denied.
• 404 (Not Found) VIRMT_TenantWithSpecifiedIdNotFound – a tenant with the specified identifier is not found in the Integration Server database.
• 404 (Not Found) VIRMT_VmWithSpecifiedIdNotFound – virtual machine with the specified identifier is not found in the Integration Server database.

Removing a tenant

Depending on the tenant type and specified parameters, lets you perform the following actions:

• For a complete tenant:
  • Delete information about the tenant and tenant virtual machines from the Integration Server database.
  • Delete the tenant protection infrastructure in Kaspersky Security Center (virtual Administration Server, account for connecting to it, structure of folders and administration groups, policies, tasks, and installation packages). If there are no other tenants, the Multitenancy KSV LA folder is also deleted.
  • Delete information about the tenant's virtual Administration Server from the Integration Server database.

  Calling the tenant removal method does not disable protection on tenant virtual machines. To disable protection, you need to perform all steps of the tenant removal procedure, including removal of Light Agent for Windows, Light Agent for Linux, and Kaspersky Security Center Network Agent from the virtual machines. To suspend protection of the virtual machine for a complete tenant, use the tenant deactivation method.

• For a simple tenant: remove the tenant from the Integration Server database.

Method:

DELETE /api/2.0/virtualization/tenants/{tenant ID}?removeTenantArtifacts={true|false}

where:

• {tenant ID} – tenant identifier in the Integration Server database (required parameter).
• removeTenantArtifacts={true|false} – optional parameter that indicates whether the tenant protection infrastructure must be removed when removing the tenant from the Integration Server database. Possible values:
  • true – when the tenant is removed, the following actions are performed:
    • Remove the tenant's virtual Administration Server.
    • Delete the administrator account of the tenant's virtual Administration Server.
    • Delete the Multitenancy KSV LA → <Tenant name> folder and its contents.
    • Delete the Multitenancy KSV LA folder if there are no other tenants.
  • false – the tenant is only deleted from the Integration Server database; the tenant protection infrastructure is not deleted.

The request is executed asynchronously, REST API returns identifier of the DeleteTenant task. You can use the task to monitor the progress of the tenant removal procedure. When the task completes, the result field displays information about the removed tenant or an error message.

In case of an error at any step of the procedure, all the changes are rolled back.

Return codes:

• 202 (Accepted) – the request is accepted for execution. The response returns the identifier of the DeleteTenant task.
• 403 (Forbidden) – access to the resource is denied.

Error codes in the task:

• VIRMT_TenantWithSpecifiedIdNotFound – a tenant with the specified identifier is not found in the Integration Server database.
• KSC_ServiceNotConfigured – Kaspersky Security Center connection settings are not specified.

Methods for working with reports

Using the Integration Server REST API, you can perform the following actions when working with tenant protection reports:

• Generate a report
• Upload a report

Report generation

Allows you to generate a report based on data saved to the Integration Server database, taking into account the specified report settings. You can specify the tenant about whose protection you want to generate a report, as well as the time interval for which you want to receive data.

In the header of the Accept request, pass the data output format: Accept:application/csv.

Method:

POST /api/2.0/virtualization/reports/tenants?tenantId={tenant ID}&from={date and time}&to={date and time}

where:

• tenantId={tenant ID} – tenant identifier in the Integration Server database. If a tenant is specified, the report includes only information about periods of protection of the virtual machines of this tenant. If a tenant is not specified, the report will include data on all virtual machines that were protected during the specified period.
• from={date and time} – start date and time of the reporting period in YYYY-MM-DDThh:mm:ss format. If the value is not specified, the date of the earliest record in the Integration Server database is used.
• to={date and time} – end date and time of the reporting period in YYYY-MM-DDThh:mm:ss format. If the value not specified, the current date is used.

The request is executed asynchronously, REST API returns identifier of the CreateTenantReport task. Using the task, you can monitor the progress of the report generation procedure. When the task execution completes, the result field displays the report identifier or an error message.

Return codes:

• 202 (Accepted) – the request is accepted for execution. The response returns the identifier of the CreateTenantReport task.
• 403 (Forbidden) – access to the resource is denied.
• 404 (Not Found) – a tenant with the specified identifier is not found in the Integration Server database.

Report upload

Allows you to upload a report generated before.

In the header of the Accept request, pass the data output format: Accept: application/csv.

The report can be uploaded in parts. You can specify the data range in the Range request header, for example:

Range: bytes=0-1023

In response to a request with this header, the REST API returns the 206 (Partial content) result and the first kilobyte of data. The response contains the Content-Range and Content-Length headers.

For example:

Content-Range: bytes=0-1023/123456

Content-Length: 1024

Method:

GET /api/2.0/virtualization/reports/tenants/{report ID}

where:

{report ID} – report identifier obtained as a result of successful completion of the CreateTenantReport task (required parameter).

Return codes:

• 200 (OK) – request completed successfully. The response returns the report data in the format specified in the Accept header.
• 206 (Partial content) – request completed successfully. The response returns the part of the report specified by the Range heading.
• 403 (Forbidden) – access to the resource is denied.
• 404 (Not Found) – report with the specified identifier is not found.
• 415 (Unsupported Media Type) – unsupported format of the requested data (incorrect format was passed in the Accept request header).

Methods for working with tasks

The tasks are used for processing requests that are time consuming and run asynchronously. Task statuses allow you to monitor the progress of actions specified in the request.

A task may have one of the following states:

• Created – task is created but not started.
• Starting – the task is in the process of starting.
• Running – the task is running. For a task in this state, the execution progress is displayed as a percent value.
• Completed – the task has been successfully completed. For a task in this state, the task execution result is displayed. The result contains task-specific data, for example, the identifier of a new tenant after the CreateTenant task completes.
• Stopping – the task is being prepared for completion. If you stopped a task, it may be in this state before switching to the Canceled state.
• Failed – the task failed. For a task in this state, detailed error information is indicated.
• Canceled – the task is terminated by the user or the system. For a task in this state, detailed error information is indicated.
• Queued – the task has been queued and is waiting for execution to start.

By means of the Integration Server REST API, you can perform the following tasks:

• Get a list of tasks
• Get information about a specified task
• Cancel execution of a specified task

Getting task information

Allows you to get information about the task by its identifier.

Method:

GET /api/2.0/virtualization/tasks/{ID}

where:

{ID} – task identifier (required parameter).

In case of successful completion of the request, the REST API returns the following information about the task:

<task id="{ID}" created="{date and time}" stateChanged="{date and time}" changed="{date and time}">

<state>{state}</state>

<type>{type}</type>

<stage>{stage}</stage>

<progress>{execution progress}</progress>

<result>{result}</result>

<!-- If the task execution fails, an error message is displayed instead of the result.

<error>{error message}</error>

</task>

where:

• {ID} – task ID.
• created="{date and time}" – task creation time in YYYY-MM-DDThh:mm:ss format.
• stateChanged="{date and time}" – time of the task state change in YYYY-MM-DDThh:mm:ss format.
• changed="{date and time}" – task change time in YYYY-MM-DDThh:mm:ss format.
• {state} – task state.
• {type} – task type. For example:
  • CreateTenant – a task that is used in the tenant creation procedure.
  • ChangeTenantActivation – a task that is used in tenant activation and deactivation procedures.
  • DeleteTenant – a task that is used in the tenant deletion procedure.
  • CreateTenantReport – a task that is used in the procedure for generating a tenant protection report.
• {name} – task name.
• {stage} – task execution stage.
• {execution progress} – the progress of task execution indicated as a percentage.
• {result} – result of executing the task, for example, information about a created tenant or a report identifier.
• {error message} – if an error occurs during task execution, an error message is displayed.

Return codes:

• 200 (OK) – request completed successfully.
• 403 (Forbidden) – access to the resource is denied.
• 404 (Not Found) – task with the specified identifier is not found in the Integration Server database.

Getting a list of tasks

Allows you to get a list of all existing tasks and information about each task in the list.

Method:

GET /api/2.0/virtualization/tasks?createdFrom={date and time}&state={status}&type={type}

where:

• createdFrom={date and time} – date and time in YYYY-MM-DDThh:mm:ss format (optional parameter). If the parameter is specified, the list displays the tasks that were created not earlier than the specified date and time.
• state={state} – task state (optional parameter). If the parameter is specified, the list displays only the tasks with the specified state.
• type={type} – task type (optional parameter). If the parameter is specified, the list displays only the tasks of the specified type.

Return codes:

• 200 (OK) – request completed successfully. The response returns a list of tasks.
• 403 (Forbidden) – access to the resource is denied.

Canceling a task

Allows you to stop running tasks. Some tasks cannot be completed immediately. In this case, the 202 (Accepted) code is returned and the task state changes to Stopping.

Method:

POST /api/2.0/virtualization/tasks/{ID}/cancel

where:

{ID} – task identifier (required parameter).

Return codes:

• 200 (OK) – request completed successfully (the task was canceled).
• 202 (Accepted) – request is accepted for execution (the task state changes to Stopping).
• 403 (Forbidden) – access to the resource is denied.
• 404 (Not Found) – task with the specified identifier is not found.
• 405 (Method Not Allowed) – for child tasks: you can cancel a child task only if you cancel the parent task.
• 409 (Conflict) – the task is already in one of the following states: Cancelled, Failed, Stopped.