Jump to content
Kaspersky Support Forum

KSC API use cases examples - tasks results and statistics data for Dashboards and Reports [KSC for Windows]

Antipova Anna
 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 - retrieving tasks results and statistics data for Dashboards and Reports.

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

Examples

  • 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
  • All requests are in cUrl format, 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 expamle https://www.base64encode.org/ can be used for encoding.

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

Policies changes alert \ Critical task status

Audit events available

image.thumb.png.1ec44ab1d2c46da4a28ad6e83462fc75.png

Create event processing iterator with filter (EventProcessingFactory::CreateEventProcessing2) :

EventProcessingFactory::CreateEventProcessing2) 
curl --location --request POST 'https://localhost:13299/api/v1.0/EventProcessingFactory.CreateEventProcessing2' --header 'X-KSC-Session: nT0T9KvkIKlgHGGaZ60j38Q==' --header 'Content-Type: application/json' --data-raw '{
        "pFilter": {
        "EVP_INCL_GNRL_EVENTS": true,
        "EVP_INCL_TASK_STATES": false,
        "EVP_MAX_EVENTS_COUNT": 3000,
        "KLEVP_EVENT_GNRL_TYPES_ARRAY": [
          "KLAUD_EV_SERVERCONNECT",
          "KLAUD_EV_OBJECTMODIFY",
          "KLAUD_EV_TASK_STATE_CHANGED",
          "KLAUD_EV_ADMGROUP_CHANGED",
          "KLAUD_EV_SERVERDISCONNECT",
          "KLAUD_EV_OBJECTPROPMODIFIED",
          "KLAUD_EV_OBJECTACLMODIFIED"
        ],
        "Name": "Audit events",
        "PredefinedID": "PREDEFINED_QUERY_ID_AUDIT_EVENTS"},
        "vecFieldsToReturn": [
        "event_db_id",
        "rise_time",
        "hostname",
        "hostdn",
        "event_type",
        "event_type_display_name",
        "GNRL_EA_DESCRIPTION",
        "group_id",
        "group_name",
        "product_name",
        "product_version",
        "product_displ_version",
        "GNRL_EA_SEVERITY",
        "GNRL_EA_PARAM_1",
        "GNRL_EA_PARAM_8",
        "task_display_name",
        "registration_time",
        "KLVSRV_DN",
        "KLEVP_EVENT_GROUP_TASK_ID",
        "GNRL_EA_PARAM_3"
      ],
        "vecFieldsToOrder": [],
        "lifetimeSec": 1000
}'

Response ID

Response
{"strIteratorId":"A07B69A5347CF435DB66C0FA826371FF"}

Get result from Response data ( ReportManager::GetStatisticsData) :

EventProcessing::GetRecordRange
curl --location --request POST 'https://localhost:13299/api/v1.0/EventProcessing.GetRecordRange' --header 'X-KSC-Session: nT0T9KvkIKlgHGGaZ60j38Q==' --header 'Content-Type: application/json' --data-raw '{
    "strIteratorId":"A07B69A5347CF435DB66C0FA826371FF",
    "nStart": 0,
    "nEnd": 100
    }'

Response statistics dashboard:

Response
{"pParamsEvents":{"KLEVP_EVENT_RANGE_ARRAY" .....
Detection of threats:

image.thumb.png.b17f9ac63e28002141413d9cb9da1df0.png

Create event processing iterator with filter (EventProcessingFactory::CreateEventProcessing2) :

EventProcessingFactory::CreateEventProcessing2) 
curl --location --request POST 'https://localhost:13299/api/v1.0/EventProcessingFactory.CreateEventProcessing2' --header 'X-KSC-Session: n/euPaWcHBCk5Oz76XFLsSg==' --header 'Content-Type: application/json' --data-raw '{
        "pFilter": {
        "KLEVP_EVENT_TYPE": "GNRL_EV_VIRUS_FOUND"},
        "vecFieldsToReturn": [
        "event_db_id",
        "rise_time",
        "hostname",
        "hostdn",
        "event_type",
        "event_type_display_name",
        "GNRL_EA_DESCRIPTION",
        "group_id",
        "group_name",
        "product_name",
        "product_version",
        "product_displ_version",
        "GNRL_EA_SEVERITY",
        "GNRL_EA_PARAM_1",
        "GNRL_EA_PARAM_8",
        "task_display_name",
        "registration_time",
        "KLVSRV_DN",
        "KLEVP_EVENT_GROUP_TASK_ID"
      ],
        "vecFieldsToOrder": [],
        "lifetimeSec": 1000
}'

Response ID

Response
{"strIteratorId":"48E14F430EF0058BB039929318693123"}

Get result from Response data ( ReportManager::GetStatisticsData) :

EventProcessing::GetRecordRange
curl --location --request POST 'https://localhost:13299/api/v1.0/EventProcessing.GetRecordRange' --header 'X-KSC-Session: n/euPaWcHBCk5Oz76XFLsSg==' --header 'Content-Type: application/json' --data-raw '{
          "strIteratorId": "48E14F430EF0058BB039929318693123",
          "nStart": 0,
          "nEnd": 20
        }'

Response statistics dashboard:

Response
{"pParamsEvents":{"KLEVP_EVENT_RANGE_ARRAY" .....

Critical task status

Status of Critical task:

  • Backup of Administration Server data,
  • Administration Server maintenance,
  • Download updates to the Administration Server repository.

for example - Backup of Administration Server data

#strTask - open task in nmw-web-console - 148 (for example: https://localhost:8080/#/management/tasks/148)

image.thumb.png.012cc732ed217470bf4ceb5bfce94652.png

Acquire task execution history events (Tasks::GetTaskHistory)

Tasks::GetTaskHistory
curl --location --request POST 'https://localhost:13299/api/v1.0/Tasks.GetTaskHistory' --header 'X-KSC-Session: n/Uvfki+u+pAmb8jjMzVBzg==' --header 'Content-Type: application/json' --data-raw '{
    "pSortFields":  [{"type":"params","value":{"Name":"rise_time","Asc":false}}],
    "pFields2Return": [
        "hostdn",
        "group_name",
        "task_new_state",
        "KLVSRV_DN",
        "rise_time",
        "GNRL_EA_DESCRIPTION"
    ],
    "strHostName": "KSC", # Hostname Administration Server
    "pFilter": {
        "type": "params",
        "value": {}
    },
    "strTask": "103" # from nmw-web-console
}'

Response ID

Response
{"strIteratorId":"2C356F1FA5B5875980950999AD036094"}

Get result from Response data ( ReportManager::GetStatisticsData) :

EventProcessing::GetRecordRange
curl --location --request POST 'https://localhost:13299/api/v1.0/EventProcessing.GetRecordRange' --header 'X-KSC-Session: na2b5M8XFBGHmP+P5+tDYcg==' --header 'Content-Type: application/json' --data-raw '{
          "strIteratorId": "2C356F1FA5B5875980950999AD036094", #strIteratorId from response
          "nStart": 0,
          "nEnd": 20
        }'

Response statistics dashboard:

Response
{"pParamsEvents":{"KLEVP_EVENT_RANGE_ARRAY":[{"type":"params","value":{"group_name":"Managed devices","hostdn":"KSC","rise_time":{"type":"datetime","value":"2022-01-18T11:47:57Z"},"task_new_state":1}},{"type":"params","value":{"GNRL_EA_DESCRIPTION":"Invalid destination folder. ","group_name":"Managed devices","hostdn":"KSC","rise_time":{"type":"datetime","value":"2022-01-18T11:46:03Z"},"task_new_state":3}},{"type":"params","value":{"group_name":"Managed devices","hostdn":"KSC","rise_time":{"type":"datetime","value":"2022-01-18T11:46:03Z"},"task_new_state":1}},{"type":"params","value":{"group_name":"Managed devices","hostdn":"KSC","rise_time":{"type":"datetime","value":"2022-01-18T11:46:02Z"},"task_new_state":32}},{"type":"params","value":{"group_name":"Managed devices","hostdn":"KSC","rise_time":{"type":"datetime","value":"2022-01-18T11:45:58Z"},"task_new_state":32}},{"type":"params","value":{"group_name":"Managed devices","hostdn":"KSC","rise_time":{"type":"datetime","value":"2022-01-18T11:45:58Z"},"task_new_state":1}},{"type":"params","value":{"group_name":"Managed devices","hostdn":"KSC","rise_time":{"type":"datetime","value":"2022-01-16T23:04:00Z"},"task_new_state":4}},{"type":"params","value":{"group_name":"Managed devices","hostdn":"KSC","rise_time":{"type":"datetime","value":"2022-01-14T23:04:00Z"},"task_new_state":4}}]}}

Information at Reports

Enumerates all existing reports.

ReportManager.EnumReports
curl --location --request POST 'https://localhost:13299/api/v1.0/ReportManager.EnumReports' --header 'X-KSC-Session: nejYJnFLwJgs14KpxeH9UMA=='

Response all reports:

Response 
{
    "PxgRetVal": [
        {
            "type": "params",
            "value": {
                "RPT_CREATED": {
                    "type": "datetime",
                    "value": "2021-04-30T12:39:00Z"
                },
                "RPT_DN": "Report on file operations on removable drives",
                "RPT_EXTRA_DATA": {
                    "type": "params",
                    "value": {
                        "KLRPT_DONT_USE_SPACES_FOR_SLASHES": false,
                        "KLRPT_EXPAND_PERIOD": true,
                        "KLRPT_GLOBAL_SCOPE": false,
                        "KLRPT_OWNER_SRV_INSTANCE": "e71217d1-4a96-462c-a56a-6112bdc5369b",
                        "KLRPT_PROTECTION_INCLUDE_OK": false,
                        "KLRPT_PROTECTION_INCLUDE_VM": true,
                        "KLRPT_PROTECTION_INCLUDE_WARNING": true,
                        "KLRPT_REPORT_ID": 27, #lReportId for next command Execute report ( ReportManager::ExecuteReportAsync)
                        "KLRPT_SLAVE_EXEC_TIMEOUT": 300,
                        "KLRPT_SLAVE_REC_DEPTH": 1,
                        "KLRPT_TEMPORAL": false
                    }
                },
                "RPT_GROUP_ID": 0,
                "RPT_ID": 27, #lReportId for next command Execute report ( ReportManager::ExecuteReportAsync)
                "RPT_MODIFIED": {
                    "type": "datetime",
                    "value": "2021-04-30T12:39:00Z"
                },
                "RPT_TYPE": 0
            }
        },

USB Data transfer alert \  Report on file operations on removable drives available

Execute report ( ReportManager::ExecuteReportAsync)

ReportManager::ExecuteReportAsync
curl --location --request POST 'https://localhost:13299/api/v1.0/ReportManager.ExecuteReportAsync' --header 'X-KSC-Session: na2b5M8XFBGHmP+P5+tDYcg==' --header 'Content-Type: application/json' --data-raw '{
    "lReportId": 27,
    "pOptions": {
        "KLRPT_OUTPUT_FORMAT": {
            "type": "params",
            "value": {
                "KLRPT_TARGET_TYPE": 2
            }
        }
    }
}'

Response ID

Response
{"strRequestId":"e54ff81b-bfe7-46bb-8f60-de1865bce47c"}

Check status of the async action (AsyncActionStateChecker::CheckActionState)

AsyncActionStateChecker::CheckActionState
curl --location --request POST 'https://localhost:13299/api/v1.0/AsyncActionStateChecker.CheckActionState' --header 'X-KSC-Session: na2b5M8XFBGHmP+P5+tDYcg==' --header 'Content-Type: application/json' --data-raw '{"wstrActionGuid":"e54ff81b-bfe7-46bb-8f60-de1865bce47c"}'

Response KLRPT_OUTPUT_FILE

Response
{"bFinalized":true,"bSuccededFinalized":true,"lStateCode":1,"pStateData":{"KLRPT_OUTPUT_FILE":"/KLRT/2f4a6361-ebeb-42d6-b044-03dc30573a83.json","KLRPT_OUTPUT_FORMAT":{"type":"params","value":{"KLRPT_TARGET_TYPE":2}}},"lNextCheckDelay":0}

Get Data

Get
curl --location --request GET 'https://localhost:13299/KLRT/2f4a6361-ebeb-42d6-b044-03dc30573a83.json' --header 'X-KSC-Session: na2b5M8XFBGHmP+P5+tDYcg=='

Response with the report data:

Response
{"data":{"summary":{"heading":"Report on file operations on removable drives","subhead":"Report on file operations on removable drives","description":"This report provides information about file operations performed on removable drives. This report is generated for all groups.", ......

Commands can be used for all reports:

  • Server health status
  • Threat detection details from reports
  • Software Vulnerability details from Report on vulnerabilities
  • etc.

information at Dashboard

KLRPT_DSH_TYPE - List of statistics dashboards types and attributes

KLRPT_DSH_TYPE
Diagram
Meaning
22

image.png.a9d76667321a58e31377a5d401838f71.png

Distribution of anti-virus bases versions on hosts (5 counters: actual, 1 day old, 3-days old, 7-days old, and more than 7 days old).
detection of threats - 56
prohibited applications - 42
Most heavily infected devices - 14
Most frequent threats - 18, 19

image.thumb.png.816fbed633bfeee0f0e0e2bbb680f312.png

Threat detection details (Critical, High, Medium)
40

image.thumb.png.31bd61a823b6722926ee39224d3dda57.png

Distribution of hosts with different vulnerability status (critical, high, warning, none).
26

image.thumb.png.6148a8c177cd41c92c74a724d8a12c1c.png

License usage.

8

20

image.thumb.png.e6adef489500b02e507d9dd0db72825a.png

8 - Distribution of anti-virus protection states in time.

20 - Current state of the most anti-virus protection (number of hosts with the status Critical, Warning, and OK).

 

AV Definition Status

Send Request to obtain required data( ReportManager::RequestStatisticsData) :

ReportManager::RequestStatisticsData
curl --location --request POST 'https://127.0.0.1:13299/api/v1.0/ReportManager.RequestStatisticsData' --header 'X-KSC-Session: npczf1aapMkBcNOV9rhVgHA==' --header 'Content-Type: application/json' --data-raw '{
    "pRequestParams": {
        "KLPPT_DASHBOARD": {
            "type": "params",
            "value": {
                "AV-DB-2": { #AV-DB-2 - Same requested unique name (GUID)
                    "type": "params",
                    "value": {
                        "KLRPT_DSH_TYPE": 22, #22 - value from table List of statistics dashboards types and attributes
                        "bIncludeVS": false,
                        "id": 0
                    }
                }
            }
        }
    }
}'

Response ID

Response
{"strRequestId": "BA357813B44D88306228D8614B081C11"}

Get result from Response data operation ( ReportManager::GetStatisticsData) :

ReportManager::GetStatisticsData
curl --location --request POST 'https://127.0.0.1:13299/api/v1.0/ReportManager.GetStatisticsData' --header 'X-KSC-Session: npczf1aapMkBcNOV9rhVgHA==' --header 'Content-Type: application/json' --data-raw '{"strRequestId": "E71313D620483B40309EA81415C34005"}'
#strRequestId from ReportManager.RequestStatisticsData

Response statistics dashboard:

Response
{"pResultData":{"KLPPT_DASHBOARD":{"type":"params","value":{"AV-DB-2":{"type":"params","value":{"KLRPT_DSH_TYPE":22,"bIncludeVS":false,"id":0,"nCount3Days":0,"nCount7Days":4,"nCountActual":1,"nCountDay":0,"nCountOld":1}}}}}}

 

Threat detection details (Critical, High, Medium)

Send Request to obtain required data ( ReportManager::RequestStatisticsData) :

ReportManager::RequestStatisticsData 
curl --location --request POST 'https://localhost:13299/api/v1.0/ReportManager.RequestStatisticsData' --header 'X-KSC-Session: nz3Z1sQYVGWmpOcuBbRfjGQ==' --header 'Content-Type: application/json' --data-raw '{
"pRequestParams": {
"KLPPT_DASHBOARD": {
"type": "params",
"value":
    {
  "threatsDetection-1": { #GUID
"type": "params",
"value": {
          "KLPPT_StatPeriodInSec": 2592000,
          "KLRPT_DSH_TYPE": 56,
          "bIncludeVS": false,
          "id": 0
        }},
    "prohibitedApps-1": { #GUID
"type": "params",
"value": {
          "KLPPT_StatPeriodInSec": 2592000,
          "KLRPT_DSH_TYPE": 42,
          "bIncludeVS": false,
          "id": 0
        }},
    "infectedDevices-1":  { #GUID
"type": "params",
"value": {
          "KLPPT_StatPeriodInSec": 2592000,
          "KLRPT_DSH_TYPE": 14,
          "bIncludeVS": false,
          "id": 0
        }},
        "frequentThreats0":  { #GUID
"type": "params",
"value": {
          "KLPPT_StatPeriodInSec": 2592000,
          "KLRPT_DSH_TYPE": 18,
          "bIncludeVS": false,
          "id": 0
        }},
        "frequentThreats1":  { #GUID
"type": "params",
"value": {
          "KLPPT_StatPeriodInSec": 2592000,
          "KLRPT_DSH_TYPE": 19,
          "bIncludeVS": false,
          "id": 0
        }}        
}
}
}
}'

Response ID

Response
{"strRequestId": "D988500C858EBAE332816C34E5588F7F"}

Get result from Response data operation ( ReportManager::GetStatisticsData) :

ReportManager:GetStatisticsData
curl --location --request POST 'https://localhost:13299/api/v1.0/ReportManager.GetStatisticsData' --header 'X-KSC-Session: nz3Z1sQYVGWmpOcuBbRfjGQ==' --header 'Content-Type: application/json' --data-raw '{"strRequestId": "D988500C858EBAE332816C34E5588F7F"}'

Response statistics dashboard:

Response 
{"pResultData":{"KLPPT_DASHBOARD":{"type":"params","value":{"frequentThreats01":{"type":"params","value":{"DSHT_DATA":[{"type":"params","value":{"nCount":28,"wstrName":"EICAR-Test-File"}},{"type":"params","value":{"nCount":28,"wstrName":"UDS:HackTool.Win32.CreDump.cr"}},{"type":"params","value":{"nCount":24,"wstrName":"UDS:Trojan.Win32.Generic"}},{"type":"params","value":{"nCount":19,"wstrName":"HEUR:Trojan-PSW.Win64.Mimikatz.gen"}},{"type":"params","value":{"nCount":15,"wstrName":"Trojan-PSW.Win32.Mimikatz.gen"}},{"type":"params","value":{"nCount":5,"wstrName":"HEUR:Trojan-PSW.Win64.Convagent.gen"}},{"type":"params","value":{"nCount":2,"wstrName":"UDS:Trojan.Win32.Agent.xadwev"}},{"type":"params","value":{"nCount":1,"wstrName":"Trojan.Multi.GenAutorunProc.a"}},{"type":"params","value":{"nCount":1,"wstrName":"http://bug.qainfo.ru/test/wmuf_w/"}}],"KLPPT_StatFinishTime":{"type":"datetime","value":"2022-01-18T16:14:27Z"},"KLPPT_StatPeriodInSec":2592000,"KLPPT_StatStartTime":{"type":"datetime","value":"2021-12-19T16:14:27Z"},"KLRPT_DSH_TYPE":18,"bIncludeVS":false,"id":0}},"frequentThreats12":{"type":"params","value":{"DSHT_DATA":[{"type":"params","value":{"nCount":27,"wstrName":"UDS:HackTool.Win32.CreDump.cr"}},{"type":"params","value":{"nCount":22,"wstrName":"UDS:Trojan.Win32.Generic"}},{"type":"params","value":{"nCount":9,"wstrName":"EICAR-Test-File"}},{"type":"params","value":{"nCount":4,"wstrName":"HEUR:Trojan-PSW.Win64.Mimikatz.gen"}},{"type":"params","value":{"nCount":3,"wstrName":"Trojan-PSW.Win32.Mimikatz.gen"}},{"type":"params","value":{"nCount":1,"wstrName":"HEUR:Trojan-PSW.Win64.Convagent.gen"}}],"KLPPT_StatFinishTime":{"type":"datetime","value":"2022-01-18T16:14:27Z"},"KLPPT_StatPeriodInSec":2592000,"KLPPT_StatStartTime":{"type":"datetime","value":"2021-12-19T16:14:27Z"},"KLRPT_DSH_TYPE":19,"bIncludeVS":false,"id":0}},"infectedDevices-2":{"type":"params","value":{"DSHT_DATA":[{"type":"params","value":{"nCount":114,"wstrInternalName":"1ccdd245-2850-424a-9f63-a35b115cbced","wstrName":"WIN10-KES-EDR"}},{"type":"params","value":{"nCount":7,"wstrInternalName":"3e043993-8332-4e1c-958e-a750cd3d0c7c","wstrName":"KHRAMEEV-WIN10"}},{"type":"params","value":{"nCount":2,"wstrInternalName":"c160e768-ba47-47e7-a905-d7c3d39b74d4","wstrName":"khrameev-ub19"}}],"KLPPT_StatFinishTime":{"type":"datetime","value":"2022-01-18T16:14:27Z"},"KLPPT_StatPeriodInSec":2592000,"KLPPT_StatStartTime":{"type":"datetime","value":"2021-12-19T16:14:27Z"},"KLRPT_DSH_TYPE":14,"bIncludeVS":false,"id":0}},"prohibitedApps-2":{"type":"params","value":{"DSHT_DATA":[],"KLPPT_StatPeriodInSec":2592000,"KLRPT_DSH_TYPE":42,"bIncludeVS":false,"id":0}},"threatsDetection-2":{"type":"params","value":{"DSHT_DATA":[{"type":"params","value":{"nCount":67,"nType":1,"wstrName":"File Threat Protection"}},{"type":"params","value":{"nCount":45,"nType":10,"wstrName":"Scan task"}},{"type":"params","value":{"nCount":9,"nType":3,"wstrName":"Web Threat Protection"}},{"type":"params","value":{"nCount":2,"nType":6,"wstrName":"Host Intrusion Prevention"}}],"KLPPT_StatFinishTime":{"type":"datetime","value":"2022-01-18T16:14:28Z"},"KLPPT_StatPeriodInSec":2592000,"KLPPT_StatStartTime":{"type":"datetime","value":"2021-12-19T16:14:28Z"},"KLRPT_DSH_TYPE":56,"bIncludeVS":false,"id":0}}}}}

 

End 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
Link to comment
Share on other sites

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