Jump to content
Kaspersky Support Forum

KSC API use cases examples - publishing KSC virtual server Administration Agent package [KSC for Windows]

Antipova Anna

By Antipova Anna
in Advice and solutions for Kaspersky Security Center

 Share

Recommended Posts

Antipova Anna

Antipova Anna

Posted
Posted

Advice and Solutions (Forum Knowledgebase) Disclaimer. Read before using materials.

Description and cautions

The article shares working examples of using KSC API calls for one of the available scenarios - publishing KSC virtual server Administration Agent package.

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

  • Make sure you have Kaspersky Administration Agent available in installation packages

  • Make sure you have internal api-user with permissions for Kaspersky Security Center (main and Virtual Kaspersky Security Center)

Example

  • KSC address - 127.0.0.1 (the address can also be external and used over the network)
  • API Port - 13299 (default port of KSC API)
  • User: api-user (internal user with Kaspersky Security Center rights for KSC and vKSC), base64: YXBpLXVzZXI=
  • Password: password, base64: cGFzc3dvcmQ=

  • Authentication, type: Authenticated session, other types: KSC Open API description

  • Name vKSC: vksc2, base64: dmtzYzI=
  • Requests are described in cUrl format, it is also possible to use the python library (KlAkOAPI Python package)

Session start for connecting to the 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"'

User and password are transmitted to base64 within a secure HTTPS session.

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

Sending request to the KSC server for a list of packages (PackagesApi::GetPackages2) :

PackagesApi::GetPackages2
--header 'X-KSC-Session: nsPbUpP1oAVZlM1lODEbg8A==' #PxgRetVal from Session.StartSession

Retrieving a list of packets. Receiving KLPKG_NPI_PKGID nAgent to transmit packet to vKSC

Response 
{
    "PxgRetVal": [
        {...},
        {
            "type": "params",
            "value": {
                "KLPKG_NPI_AV_BASES_UPDATE_TIME": {
                    "type": "datetime",
                    "value": ""
                },
                "KLPKG_NPI_AV_BASES_UPD_SUPPORTED": false,
                "KLPKG_NPI_CREATION_TIME": {
                    "type": "datetime",
                    "value": "2021-04-30T12:39:00Z"
                },
                "KLPKG_NPI_EXTRA_DATA": {
                    "type": "params",
                    "value": {
                        "KLPGG_VAPM_DISTRIB_GLBID": {
                            "type": "long",
                            "value": 0
                        },
                        "KLPKG_EULA_UID": {
                            "type": "binary",
                            "value": "fPTQzfMWVvVPG7bFasjoJw=="
                        },
                        "KLPKG_FORMAT": 2,
                        "KLPKG_IS_MSI": true,
                        "KLPKG_LANG_TAG": "en",
                        "KLPKG_PARENT_ID": 0,
                        "KLPKG_PKG_MAN": 0,
                        "KLPKG_PLATFORM": 2,
                        "KLPKG_PRD_TYPE": 1,
                        "KLPKG_TYPE": 1,
                        "bPkgPrereqAllowed": true,
                        "nPatchGlbId": {
                            "type": "long",
                            "value": 0
                        },
                        "nPatchLcid": 0
                    }
                },
                "KLPKG_NPI_MODIF_TIME": {
                    "type": "datetime",
                    "value": "2021-04-30T12:39:00Z"
                },
                "KLPKG_NPI_NAME": "Kaspersky Security Center 13 Network Agent (13.0.0.11247)",
                "KLPKG_NPI_PACKAGE_PATH": "\\\\KSC\\KLSHARE\\Packages\\NetAgent_13.0.0.11247",
                "KLPKG_NPI_PKGID": 3,
                "KLPKG_NPI_PRODUCT_DISPL_NAME": "Kaspersky Security Center 13 Network Agent",
                "KLPKG_NPI_PRODUCT_DISPL_VERSION": "13.0.0.11247",
                "KLPKG_NPI_PRODUCT_NAME": "1103",
                "KLPKG_NPI_PRODUCT_VERSION": "1.0.0.0",
                "KLPKG_NPI_SIZE": {
                    "type": "long",
                    "value": 70113813
                },
                "KLPKG_NPI_SS_DESCR": "NetAgent_13.0.0.11247\\exec\\ss_install.xml|3"
            }
        },
        {...}
    ]
}

Sending request for the vKSC list (VServers::GetVServers) :

VServers:GetVServers
curl --location --request POST 'https://127.0.0.1:13299/api/v1.0/VServers.GetVServers' \
--header 'Content-Type: application/json' \
--header 'X-KSC-Session: nsPbUpP1oAVZlM1lODEbg8A==' \ #PxgRetVal from Session.StartSession
--data-raw '{
    "lParentGroup": -1
}'

Obtaining KLVSRV_DN and KLVSRV_ID

Response 
{
    "PxgRetVal": [
        {...},
        {
            "type": "params",
            "value": {
                "KLVSRV_CREATED": {
                    "type": "datetime",
                    "value": "2021-11-23T11:48:53Z"
                },
                "KLVSRV_DN": "vksc2",
                "KLVSRV_ENABLED": true,
                "KLVSRV_GROUPS": 29,
                "KLVSRV_GRP": 0,
                "KLVSRV_HST_UID": "VSRV64c559dc-17e1-459d-b9d5-4c26ec35d426",
                "KLVSRV_ID": 3,
                "KLVSRV_LIC_ENABLED": true,
                "KLVSRV_NEW_HOSTS_PROHIBITED": false,
                "KLVSRV_SUPER": 28,
                "KLVSRV_TOO_MUCH_HOSTS": false,
                "KLVSRV_UID": "VSRV64c559dc-17e1-459d-b9d5-4c26ec35d426",
                "KLVSRV_UNASSIGNED": 32
            }
        },
        {...}
    ]
}

Asynchronous request to transfer the Administration Agent installation package to vKSC and create a standalone package (PackagesApi::RetranslateToVServerAsync) :

PackagesApi:RetranslateToVServerAsync
--header 'Content-Type: application/json' \
--header 'X-KSC-Session: nsPbUpP1oAVZlM1lODEbg8A==' \ #PxgRetVal from Session.StartSession
--data-raw '{
    "nPackageId": 3, #KLPKG_LANG_TAG from PackagesApi.GetPackages2
    "nVServerId": 3, #KLVSRV_ID from VServers.GetVServers
    "pOptions": {
        "KLPKG_CREATE_STANDALONE_PRODS": false,
        "KLPKG_CREATE_STANDALONE_NAGT": true,
        "KLPKG_USE_LANGUAGE_TAG": "en", #KLPKG_LANG_TAG from PackagesApi.GetPackages2
        "KLPKG_TYPE": 1,
        "KLPKG_LAZY_RETRANSLATION": false
    }
}'

Obtaining asynchronous task ID

Response
{
    "PxgRetVal": "C51B622B891CB03B7229A3CD9407B6AD"
}

Checking status of the task (AsyncActionStateChecker::CheckActionState) :

AsyncActionStateChecker:CheckActionState
--header 'Content-Type: application/json' \
--header 'X-KSC-Session: nsPbUpP1oAVZlM1lODEbg8A==' \ #PxgRetVal from Session.StartSession
--data-raw '{
    "wstrActionGuid": "C51B622B891CB03B7229A3CD9407B6AD" #PxgRetVal form PackagesApi.RetranslateToVServerAsync
}'

Completion ("bFinalized": true) and successful execution ("bSuccededFinalized": true)

Response
{
    "bFinalized": true,
    "bSuccededFinalized": true,
    "lStateCode": 1,
    "pStateData": {
        "KLPKG_EP_EXECID": 11,
        "KLPKG_EP_FILESIZE": 0
    },
    "lNextCheckDelay": 0
}

Ending session to KSC (Session::EndSession) :

Session::EndSession
curl --location --request POST 'https://127.0.0.1:13299/api/v1.0/Session.EndSession' \
--header 'X-KSC-Session: nsPbUpP1oAVZlM1lODEbg8A==' #PxgRetVal from Session.StartSession

Starting session to connect to the virtual 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"' \
--header 'X-KSC-VServer: dmtzYzI='

The user can belong to the vKSC or to the main KSC (user account rights for Kaspersky Security Center should additionally be configured in vKSC). The user name and password are transferred to base64 format as part of a secure HTTPS session.

X-KSC-VServer - vKSC name (KLVSRV_DN from VServers.GetVServers) to base64

Response
{
    "PxgRetVal": "nz1/AOfHq6cdf986vTvNV7Q=="
}

Obtaining a list of standalone installation packages from vServer (PackagesApi::GetExecutablePackages) :

PackagesApi:GetExecutablePackages
--header 'X-KSC-Session: nz1/AOfHq6cdf986vTvNV7Q==' \ #PxgRetVal from Session.StartSession
--header 'Content-Type: application/json'

Receiving KLPKG_WebURL

Response 
{
    "PxgRetVal": {
        "KLPKG_evpExecs": [
            {...},
            {
                "type": "params",
                "value": {
                    "KLPKG_CreationDate": {
                        "type": "datetime",
                        "value": "2021-11-24T12:07:23Z"
                    },
                    "KLPKG_EP_SHA256": "",
                    "KLPKG_IsPublished": true,
                    "KLPKG_IsVirtual": true,
                    "KLPKG_LicenseSerialNum": "",
                    "KLPKG_ModificationDate": {
                        "type": "datetime",
                        "value": "2021-11-24T12:07:23Z"
                    },
                    "KLPKG_NAME": "",
                    "KLPKG_NagentDisplayVersion": "13.0.0.11247",
                    "KLPKG_NagentPkgId": 28,
                    "KLPKG_NagentPkgName": "Kaspersky Security Center 13 Network Agent (13.0.0.11247)",
                    "KLPKG_ProdDisplayName": "",
                    "KLPKG_TargetGroup": "Managed devices",
                    "KLPKG_TargetGroupId": 29,
                    "KLPKG_WebURL": "http://ksc.test.lab:8060/dlpkg?id=12712942",
                    "KLPKG_evpAddPkgId": 28,
                    "KLPKG_evpExecPkgId": 10,
                    "KLPKG_evpPkgId": 28,
                    "KLPKG_evpPkgPath": "",
                    "KLPKG_evpPkgSize": 0
                }
            },
            {...}
        ]
    }
}

Standalone Network Agent installation package is available at KLPKG_WebURL for KLPKG_NagentPkgName

Session end for vKSC (Session::EndSession) :

Session::EndSession
curl --location --request POST 'https://127.0.0.1:13299/api/v1.0/Session.EndSession' \
--header 'X-KSC-Session: nz1/AOfHq6cdf986vTvNV7Q==' #PxgRetVal from Session.StartSession

Please sign in to comment

You will be able to leave a comment after signing in



Sign In Now
 Share
Go to topic listing


×
×
  • Create New...