KSC API use cases examples - host isolation with KES/KEA [KSC for Windows]
Entry posted by svc_kms in How-to
24 views
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:
UserPasswordapi-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)
--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.
{
"PxgRetVal": "nsPbUpP1oAVZlM1lODEbg8A=="
}
|
Use this token in request header
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
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
{"strAccessor":"ppYeO5rmkvKcMUm8vQzOK2","PxgRetVal":18}
|
Copy Accessor for next request (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:
{
"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 |
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.
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:
{
"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
2) Open tab APP Settings → Network Isolation → Isolation on detection
3) Add rule for RDP → click "OK" → click "Save"
HostGroup.SS_Read
Read data from host settings storage. (HostGroup::SS_Read)
Parameters values should be taken from two previous responses
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:
{
"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
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
{ }
|
Host isolated successfully.
For off isolation you must change for pSettings past previous response and change
"Enable": false
|
|
1 Comment
Recommended Comments
Please sign in to comment
You will be able to leave a comment after signing in
Sign In Now