Jump to content
Kaspersky Support Forum

KSC API use cases examples - host isolation with KES/KEA [KSC for Windows]

svc_kms

Entry posted by svc_kms in How-to

299 views

 Share

Description and cautions

The article is giving some use cases examples of KSC API calls to ease one's start using the API. In that KB we are looking at host isolation with KES/KEA scenario.

For the Windows version of cURL, you need to specify that the arguments need to be escaped with "\", otherwise there will be an error. For example:  'Authorization: KSCBasic user=\"YXBpLXVzZXI=\", pass=\"cGFzc3dvcmQ=\", internal=\"1\"'

Details

Prerequisites

  • internal user: api-user

Example

  • KSC address - 127.0.0.1 (the address can also be external)
  • API Port - 13299 (default)
  • User: api-user (intrental KSC user), base64: YXBpLXVzZXI=
  • Password: password, base64: cGFzc3dvcmQ=

  • Credentials:

     
    User
    Password
      api-user password
    Base64: YXBpLXVzZXI= cGFzc3dvcmQ=
  • Authentication, type: Authenticated session, other types: KSC Open API description
  • Requests are in cUrl and http formats, as an alternative it is also possible to use Python library (KlAkOAPI Python package)

Login

Start connection to KSC (Session::StartSession)

Session::StartSession
curl --location --request POST 'https://127.0.0.1:13299/api/v1.0/Session.StartSession' \
--header 'Authorization: KSCBasic user="YXBpLXVzZXI=", pass="cGFzc3dvcmQ=", internal="1"'

Username and password should be encoded to base64 format as part of a secure HTTPS session. For example, https://www.base64encode.org/ can be used for encoding.

Response
{
    "PxgRetVal": "nsPbUpP1oAVZlM1lODEbg8A=="
}

Use this token in request header

image.png.432a6a7484954e7ef3a0648ae8c388f4.png

Find Host

Find host by filter string (HostGroup::FindHosts)

Filter string, contains a condition over host attributes, see also Search filter syntax.

We use "KLHST_WKS_DN" - Host display name

HostGroup::FindHosts
POST /api/v1.0/HostGroup.FindHosts HTTP/1.1
Host: localhost:13299
X-KSC-Session: nH4iKWCdxuBJWO5U4ATKSew==
Content-Type: application/json
Content-Length: 170
 
{
    "vecFieldsToReturn": [
        "KLHST_WKS_HOSTNAME",
        "KLHST_WKS_DN"
    ],
    "lMaxLifeTime": 1200,
    "wstrFilter": "(KLHST_WKS_DN=\"WIN10-*\")"
}

Response ID

Response
{"strAccessor":"ppYeO5rmkvKcMUm8vQzOK2","PxgRetVal":18}

Copy Accessor for next request (ChunkAccessor::GetItemsChunk)

ChunkAccessor::GetItemsChunk
curl -L -X POST "https://127.0.0.1:13299/api/v1.0/ChunkAccessor.GetItemsChunk" -H "X-KSC-Session: noOxgI9Ny7O5Whg/97qvcVg==" -H "Content-Type: application/json" --data-raw "{
\"strAccessor\":\"fb07haDqXIKZbQzyDsMwx1\",
\"nStart\": 0,
\"nCount\": 100
}"

Response info about host:

Response
{
    "pChunk": {
        "KLCSP_ITERATOR_ARRAY": [
            {
                "type": "params",
                "value": {
                    "KLHST_WKS_DN": "WIN10-OPTIMUM-1",
                    "KLHST_WKS_HOSTNAME": "c0816918-fbc5-4fbc-8fed-6f245756120e"
                }
            },
            {
                "type": "params",
                "value": {
                    "KLHST_WKS_DN": "WIN10-KES-11-OLD",
                    "KLHST_WKS_HOSTNAME": "ab365e11-a1c7-492b-a981-e84402b33a8f"
                }
            }
        ]
    },
 
........
    "PxgRetVal": 18
}

Copy value "KLHST_WKS_HOSTNAME" for next request

KEA Isolation

HostGroup.GetHostInfo

Acquire specified host attributes. (HostGroup::GetHostInfo)

strHostName (wstring) host name, a unique server-generated string (see KLHST_WKS_HOSTNAME attribute). It is NOT the same as computer network name (DNS-, FQDN-, NetBIOS-name)
pFields2Return (array) array of names of host attributes to return. See List of host attributes for attribute names
HostGroup.GetHostInfo
POST /api/v1.0/HostGroup.GetHostInfo HTTP/1.1
Host: localhost:13299
X-KSC-Session: nH4iKWCdxuBJWO5U4ATKSew==
Content-Type: application/json
Content-Length: 185
 
{
    "strHostName":"ab365e11-a1c7-492b-a981-e84402b33a8f",
        "pFields2Return": [
        "KLHST_WKS_HOSTNAME",
        "KLHST_WKS_DN",
        "KLHST_APP_INFO"
        ]
}

HostGroup.SS_GetNames

Get section names from host settings storage. (HostGroup::SS_GetNames)

Parameters values should be taken from the previous response.

HostGroup::SS_GetNames
POST /api/v1.0/HostGroup.SS_GetNames HTTP/1.1
Host: localhost:13299
X-KSC-Session: nqH6Qma75t/wBcQm8vlyqvQ==
Content-Type: application/json
Content-Length: 148
 
{
    "strHostName":"ab365e11-a1c7-492b-a981-e84402b33a8f",
    "strType":"SS_SETTINGS",
    "strProduct":"SOYUZ",
    "strVersion":"4.0.0.0"
}

Response:

Response
{
    "PxgRetVal": [
        ".KLNAG_SECTION_REBOOT_REQUEST",
        "85",
        "AccountLogonSettings",
        "ApplicationSettings",
        "AutoStartEntriesNotifySettings",
        "ConnectionSettings",
        "CreateProcessSettings",
        "FileChangeNotificationSettsEdr",
        "KLEVP_NF_SECTION",
        "KsnServiceSettings",
        "LoadImageSettingsEdr",
        "MaintenanceSettings",
        "MdrServiceSettings",
        "MessageBrokerSettings",
        "NetworkConnectionSettingsEdr",
        "NetworkIsolationProfilesSetts",
        "NetworkIsolationSettings", #copy this field setting
        "PasswordSettings",
        "PreventionSettings",
        "ProductPermissionSettings",
        "QuarantineSettings",
        "SandboxSettings",
        "SelfDefenceSettings",
        "UserModeApiMonitorSrvSettings",
        "WMIActivitySettings",
        "WindowsEventLogSettingsEdr",
        "WindowsRegistrySettings"
    ]
}

With NWC web console KSC create local network exteption for VPN:

1) Open host properties → Applications → KEA

image.thumb.png.cc1eda515c844fda0a7e34dd1533ed23.png

2) Open tab APP Settings → Network Isolation → Isolation on detection

image.thumb.png.9a620070b908efcaa10e1f1f6aee6605.png

3) Add rule for RDP → click "OK" → click "Save"

image.thumb.png.8375ae47786ab8b5dc349bcc6ea0dd78.png

HostGroup.SS_Read

Read data from host settings storage. (HostGroup::SS_Read)

Parameters values should be taken from two previous responses

HostGroup::SS_Read
POST /api/v1.0/HostGroup.SS_Read HTTP/1.1
Host: localhost:13299
X-KSC-Session: nqc+0P0UI+Wzuu+FREB74yQ==
Content-Type: application/json
Content-Length: 194
 
{
    "strHostName":"ab365e11-a1c7-492b-a981-e84402b33a8f",
    "strType":"SS_SETTINGS",
    "strProduct":"SOYUZ",
    "strVersion":"4.0.0.0",
    "strSection":"NetworkIsolationSettings"
}

Response info about Network Isolation with RDP rule exception:

Response
{
    "PxgRetVal": {
        "BaseSettings": {
            "type": "params",
            "value": {
                "Revision": {
                    "type": "long",
                    "value": 0
                },
                "__VersionInfo": [
                    1,
                    0
                ]
            }
        },
        "Enable": false,
        "Exclusions": [
            {
                "type": "params",
                "value": {
                    "Description": "Custom (user-defined)",
                    "Name": "Custom (user-defined)",
                    "Rules": [
                        {
                            "type": "params",
                            "value": {
                                "AppProtocolName": "RDP",
                                "Applications": [],
                                "Direction": 3,
                                "Enable": true,
                                "LocalAddress": "",
                                "LocalPort": {
                                    "type": "params",
                                    "value": {
                                        "MaxPort": 3389,
                                        "MinPort": 3389,
                                        "__VersionInfo": [
                                            1,
                                            0
                                        ]
                                    }
                                },
                                "Protocol": 0,
                                "RemoteAddress": "",
                                "RemotePort": {
                                    "type": "params",
                                    "value": {
                                        "MaxPort": 0,
                                        "MinPort": 0,
                                        "__VersionInfo": [
                                            1,
                                            0
                                        ]
                                    }
                                },
                                "UseApplications": false,
                                "UseLocalAddress": false,
                                "UseLocalPort": true,
                                "UseProtocol": false,
                                "UseRemoteAddress": false,
                                "UseRemotePort": false,
                                "__VersionInfo": [
                                    1,
                                    1
                                ]
                            }
                        }
                    ],
                    "__VersionInfo": [
                        1,
                        0
                    ]
                }
            }
        ],
        "IsolationTimeout": 1800,
        "NotifyUser": true,
        "UseIsolationTimeout": true,
        "__VersionInfo": [
            1,
            2
        ]
    }
}

Copy all response for next request.

HostGroup.SS_Write

Write data to host settings storage for isolation workstation with RDP rule. (HostGroup::SS_Write)

1) Use previous value parameters

2) for nOption use 7

  • 7 - "Clear", replaces existing section contents with pData, i.e. existing section contents will deleted and variables from pData will be written to the section. 

3) for pSettings past previous response and change 

"Enable": true

HostGroup::SS_Write
POST /api/v1.0/HostGroup.SS_Write HTTP/1.1
Host: localhost:13299
X-KSC-Session: nbpsiiOAAxiDWfMSVkgciWQ==
Content-Type: application/json
Content-Length: 1066  
 
{
    "strHostName":"bdcae680-eeaa-4279-a822-92a0d3e01dfb",
    "strType":"SS_SETTINGS",
    "strProduct":"SOYUZ",
    "strVersion":"4.0.0.0",
    "strSection":"NetworkIsolationSettings",
    "nOption":7,
    "pSettings":{
        "BaseSettings": {
            "type": "params",
            "value": {
                "Revision": {
                    "type": "long",
                    "value": 0
                },
                "__VersionInfo": [
                    1,
                    0
                ]
            }
        },
        "Enable": true, #Isolation ON
        "Exclusions": [
            {
                "type": "params",
                "value": {
                    "Description": "Custom (user-defined)",
                    "Name": "Custom (user-defined)",
                    "Rules": [
                        {
                            "type": "params",
                            "value": {
                                "AppProtocolName": "RDP", #custom rule for RDP
                                "Applications": [],
                                "Direction": 3,
                                "Enable": true,
                                "LocalAddress": "",
                                "LocalPort": {
                                    "type": "params",
                                    "value": {
                                        "MaxPort": 3389,
                                        "MinPort": 3389,
                                        "__VersionInfo": [
                                            1,
                                            0
                                        ]
                                    }
                                },
                                "Protocol": 0,
                                "RemoteAddress": "",
                                "RemotePort": {
                                    "type": "params",
                                    "value": {
                                        "MaxPort": 0,
                                        "MinPort": 0,
                                        "__VersionInfo": [
                                            1,
                                            0
                                        ]
                                    }
                                },
                                "UseApplications": false,
                                "UseLocalAddress": false,
                                "UseLocalPort": true,
                                "UseProtocol": false,
                                "UseRemoteAddress": false,
                                "UseRemotePort": false,
                                "__VersionInfo": [
                                    1,
                                    1
                                ]
                            }
                        }
                    ],
                    "__VersionInfo": [
                        1,
                        0
                    ]
                }
            }
        ],
        "IsolationTimeout": 1800,
        "NotifyUser": true,
        "UseIsolationTimeout": true,
        "__VersionInfo": [
            1,
            2
        ]
    }
}

Response

Response
{ }

Host isolated successfully.

For off isolation you must change for pSettings past previous response and change 

"Enable": false

 

 

 

 Share

0 Comments

Recommended Comments

There are no comments to display.

Please sign in to comment

You will be able to leave a comment after signing in



Sign In Now


×
×
  • Create New...