Kaspersky Next XDR Expert Help

Name	Data type	Mandatory	Description	Value example
page	number	No	The page number. Starts with 1. The page size is 100 entries. If the value is not specified or set to a value below 1, the 1 value is used.	1
id	string	No	The alert id. If multiple values are specified, a list is formed to which the OR logical operator is applied. If no alert with a specified id is found, this id value is ignored. If no id value is specified, all alerts for the specified tenants are returned.	00000000-0000-0000-0000-000000000000
tenantID	string	Yes	The tenant id. If multiple values are specified, a list is formed to which the OR logical operator is applied. If the user does not have the Read right for any of the specified tenants, the query fails.	00000000-0000-0000-0000-000000000000
name	string	No	The alert name. A case-insensitive regular expression (PCRE).	alert ^My alert$
timestampField	string	No	The alert data field used to sort (in descending order) and filter (the from and to parameters) the list of alerts. The default value is lastSeen.	lastSeen firstSeen
from	string	No	The start of the time interval used to filter the list of alerts, in RFC3339 format. Use the timestampField value to specify the alert data field.	2021-09-06T00:00:00Z 2021-09-06T00:00:00.000Z 2021-09-06T00:00:00Z+00:00
to	string	No	The end of the time interval used to filter the list of alerts, in RFC3339 format. Use the timestampField value to specify the alert data field.	2021-09-06T00:00:00Z 2021-09-06T00:00:00.000Z 2021-09-06T00:00:00Z+00:00
status	string	No	The alert status. If multiple values are specified, a list is formed to which the OR logical operator is applied.	new inProgress inIncident closed
withEvents	bool	No	Specifies whether to include normalized events from KUMA.	/xdr/api/v1/alerts?withEvents /xdr/api/v1/alerts?withEvents=123
withAffected	bool	No	Specifies whether to include detailed data about assets and accounts related to the alerts.	/xdr/api/v1/alerts?withAffected /xdr/api/v1/alerts?withAffected=123
withHistory	bool	No	Specifies whether to include data about changes made to the alerts.	/xdr/api/v1/alerts?withHistory /xdr/api/v1/alerts?withHistory=123

Response

HTTP code: 200

Format: JSON

Example:

{
  "Total": 0,
  "Alerts": [
    {
      "ID": 0,
      "InternalID": "881dee1f-380d-4366-a2d8-094e0af4c3f6",
      "TenantID": "string",
      "Assets": [
        {
          "Data": {},
          "ID": "string",
          "IsAttacker": true,
          "IsVictim": true,
          "KSCServer": "string",
          "Name": "string",
          "Type": "host",
          "HostInfo": {
            "ID": "string",
            "TenantID": "string",
            "DisplayName": "string",
            "AssetSource": "string",
            "CreatedAt": 0,
            "IsDeleted": true,
            "IpAddress": [
              "string"
            ],
            "Fqdn": [
              "string"
            ],
            "MacAddress": [
              "string"
            ],
            "DirectCategories": [
              "string"
            ],
            "Weight": "low",
            "CiiCategory": "notCII",
            "OS": "string",
            "OSVersion": "string",
            "Sources": [
              "ksc"
            ],
            "LastVisible": 0,
            "Products": [
              {
                "ProductVersion": "string",
                "ProductName": "string"
              }
            ],
            "KSC": {
              "GroupID": 0,
              "GroupName": "string",
              "StatusMask": [
                0
              ],
              "StatusID": 0,
              "RtProtectionState": 0,
              "EncryptionState": 0,
              "AntiSpamStatus": 0,
              "EmailAvStatus": 0,
              "DlpStatus": 0,
              "EdrStatus": 0,
              "LastAvBasesUpdate": 0,
              "LastInfoUpdate": 0,
              "LastUpdate": 0,
              "LastSystemStart": 0,
              "VirtualServerID": 0
            },
            "KICS": {
              "status": "string",
              "risks": [
                {
                  "ID": 0,
                  "Name": "string",
                  "Category": "string",
                  "Description": "string",
                  "DescriptionURL": "string",
                  "Severity": 0,
                  "Cvss": 0
                }
              ],
              "serverIP": "string",
              "connectorID": 0,
              "deviceID": 0,
              "hardware": {
                "Model": "string",
                "Version": "string",
                "Vendor": "string"
              },
              "software": {
                "Model": "string",
                "Version": "string",
                "Vendor": "string"
              }
            }
          },
          "UserInfo": {
            "osmpId": "string",
            "tenantID": "string",
            "tenantName": "string",
            "domain": "string",
            "cn": "string",
            "displayName": "string",
            "distinguishedName": "string",
            "mail": "string",
            "mailNickname": "string",
            "mobile": "string",
            "objectSID": "string",
            "samAccountName": "string",
            "samAccountType": "string",
            "telephoneNumber": "string",
            "userPrincipalName": "string",
            "isArchived": true,
            "memberOf": [
              "string"
            ],
            "title": "string",
            "division": "string",
            "department": "string",
            "manager": "string",
            "location": "string",
            "company": "string",
            "streetAddress": "string",
            "physicalDeliveryOfficeName": "string",
            "managedObjects": [
              "string"
            ],
            "userAccountControl": "string",
            "whenCreated": 0,
            "whenChanged": 0,
            "accountExpires": 0,
            "badPasswordTime": 0
          }
        }
      ],
      "Assignee": {
        "ID": "string",
        "Name": "string"
      },
      "CreatedAt": "2024-01-16T09:55:50.417Z",
      "DetectionTechnologies": [
        "string"
      ],
      "Extra": {
        "additionalProp1": "string",
        "additionalProp2": "string",
        "additionalProp3": "string"
      },
      "IncidentID": "string",
      "IncidentLinkType": "auto",
      "FirstEventTime": "2024-01-16T09:55:50.417Z",
      "LastEventTime": "2024-01-16T09:55:50.417Z",
      "MITRETactics": [
        {
          "ID": "string"
        }
      ],
      "MITRETechniques": [
        {
          "ID": "string"
        }
      ],
      "Observables": [
        {
          "Details": "string",
          "Type": "ip",
          "Value": "string"
        }
      ],
      "OriginalEvents": [
        {}
      ],
      "Rules": [
        {
          "Confidence": "high",
          "Custom": true,
          "ID": "string",
          "Name": "string",
          "Severity": "critical",
          "Type": "string"
        }
      ],
      "Severity": "critical",
      "SourceCreatedAt": "2024-01-16T09:55:50.417Z",
      "SourceID": "string",
      "ExternalRef": "string",
      "Status": "new",
      "StatusChangedAt": "2024-01-16T09:55:50.417Z",
      "StatusResolution": "truePositive",
      "UpdatedAt": "2024-01-16T09:55:50.417Z"
      "HistoryRecords": [
        {
          "entityID": "string",
          "entityKind": "Alert",
          "tenantID": "string",
          "type": "alertAssigned",
          "createdAt": "2024-03-12T11:10:59.329Z",
          "params": {}
        }
      ]
    }
  ]
}

Possible errors

HTTP code	Description	`message` field value	`details` field value
400	The timestampField value is invalid.	invalid timestamp field
400	The from value is invalid.	cannot parse from	variable
400	The to value is invalid.	cannot parse to	variable
400	The id value is not in the UUID format.
400	The status value is invalid.	invalid status
403	The user does not have the required right in the Alerts and incidents functional area in any of the specified tenants.	access denied
500	Any other internal errors.	variable	variable

Page top

Viewing a list of incidents

GET /xdr/api/v1/incidents

Returns a list of incidents for the specified tenants.

Example:

https://api.example.com/xdr/api/v1/incidents?tenantID=00000000-0000-0000-0000-000000000000&withHistory

Query parameters

Name	Data type	Mandatory	Description	Value example
page	number	No	The page number. Starts with 1. The page size is 100 entries. If the value is not specified or set to a value below 1, the 1 value is used.	1
id	string	No	The incident id. If multiple values are specified, a list is formed to which the OR logical operator is applied. If no incident with a specified id is found, this id value is ignored. If no id value is specified, all incidents for the specified tenants are returned.	00000000-0000-0000-0000-000000000000
tenantID	string	Yes	The tenant id. If multiple values are specified, a list is formed to which the OR logical operator is applied. If the user does not have the Read right for any of the specified tenants, the query fails.	00000000-0000-0000-0000-000000000000
name	string	No	The incident name, in the Perl Compatible Regular Expression (PCRE) format. If no name value is specified, all incidents for the specified tenants are returned.	incident ^My incident$
timestampField	string	No	The incident data field used to filter the list of incidents. Use the from and to values to specify the time interval.	createdAt updatedAt statusChangedAt
from	string	No	The start of the time interval used to filter the list of incidents, in RFC3339 format. Use the timestampField value to specify the incident data field.	2021-09-06T00:00:00Z 2021-09-06T00:00:00.000Z 2021-09-06T00:00:00Z+00:00
to	string	No	The end of the time interval used to filter the list of incidents, in RFC3339 format. Use the timestampField value to specify the incident data field.	2021-09-06T00:00:00Z 2021-09-06T00:00:00.000Z 2021-09-06T00:00:00Z+00:00
status	string	No	The incident status. If multiple values are specified, a list is formed to which the OR logical operator is applied.	new inProgress hold closed
withAffected	bool	No	Specifies whether to include detailed data about assets and accounts related to the incidents.	/xdr/api/v1/incidents?withAffected /xdr/api/v1/incidents?withAffected=123
withHistory	bool	No	Specifies whether to include data about changes made to the incidents.	/xdr/api/v1/incidents?withHistory /xdr/api/v1/incidents?withHistory=123

Response

HTTP code: 200

Format: JSON

Example:

{
  "Total": 0,
  "Incidents": [
    {
      "ID": 0,
      "InternalID": "881dee1f-380d-4366-a2d8-094e0af4c3f6",
      "TenantID": "string",
      "Name": "string",
      "Assets": [
        {
          "Data": {},
          "ID": "string",
          "IsAttacker": true,
          "IsVictim": true,
          "KSCServer": "string",
          "Name": "string",
          "Type": "host",
          "HostInfo": {
            "ID": "string",
            "TenantID": "string",
            "DisplayName": "string",
            "AssetSource": "string",
            "CreatedAt": 0,
            "IsDeleted": true,
            "IpAddress": [
              "string"
            ],
            "Fqdn": [
              "string"
            ],
            "MacAddress": [
              "string"
            ],
            "DirectCategories": [
              "string"
            ],
            "Weight": "low",
            "CiiCategory": "notCII",
            "OS": "string",
            "OSVersion": "string",
            "Sources": [
              "ksc"
            ],
            "LastVisible": 0,
            "Products": [
              {
                "ProductVersion": "string",
                "ProductName": "string"
              }
            ],
            "KSC": {
              "GroupID": 0,
              "GroupName": "string",
              "StatusMask": [
                0
              ],
              "StatusID": 0,
              "RtProtectionState": 0,
              "EncryptionState": 0,
              "AntiSpamStatus": 0,
              "EmailAvStatus": 0,
              "DlpStatus": 0,
              "EdrStatus": 0,
              "LastAvBasesUpdate": 0,
              "LastInfoUpdate": 0,
              "LastUpdate": 0,
              "LastSystemStart": 0,
              "VirtualServerID": 0
            },
            "KICS": {
              "status": "string",
              "risks": [
                {
                  "ID": 0,
                  "Name": "string",
                  "Category": "string",
                  "Description": "string",
                  "DescriptionURL": "string",
                  "Severity": 0,
                  "Cvss": 0
                }
              ],
              "serverIP": "string",
              "connectorID": 0,
              "deviceID": 0,
              "hardware": {
                "Model": "string",
                "Version": "string",
                "Vendor": "string"
              },
              "software": {
                "Model": "string",
                "Version": "string",
                "Vendor": "string"
              }
            }
          },
          "UserInfo": {
            "osmpId": "string",
            "tenantID": "string",
            "tenantName": "string",
            "domain": "string",
            "cn": "string",
            "displayName": "string",
            "distinguishedName": "string",
            "mail": "string",
            "mailNickname": "string",
            "mobile": "string",
            "objectSID": "string",
            "samAccountName": "string",
            "samAccountType": "string",
            "telephoneNumber": "string",
            "userPrincipalName": "string",
            "isArchived": true,
            "memberOf": [
              "string"
            ],
            "title": "string",
            "division": "string",
            "department": "string",
            "manager": "string",
            "location": "string",
            "company": "string",
            "streetAddress": "string",
            "physicalDeliveryOfficeName": "string",
            "managedObjects": [
              "string"
            ],
            "userAccountControl": "string",
            "whenCreated": 0,
            "whenChanged": 0,
            "accountExpires": 0,
            "badPasswordTime": 0
          }
        }
      ],
      "AlertIDs": [
        "string"
      ],
      "Assignee": {
        "ID": "string",
        "Name": "string"
      },
      "CreatedAt": "2024-01-16T09:56:29.939Z",
      "DetectionTechnologies": [
        "string"
      ],
      "FirstEventTime": "2024-01-16T09:56:29.939Z",
      "LastEventTime": "2024-01-16T09:56:29.939Z",
      "MITRETactics": [
        {
          "ID": "string"
        }
      ],
      "MITRETechniques": [
        {
          "ID": "string"
        }
      ],
      "Observables": [
        {
          "Details": "string",
          "Type": "ip",
          "Value": "string"
        }
      ],
      "Rules": [
        {
          "Confidence": "high",
          "Custom": true,
          "ID": "string",
          "Name": "string",
          "Severity": "critical",
          "Type": "string"
        }
      ],
      "Severity": "critical",
      "ExternalRef": "string",
      "Status": "open",
      "StatusChangedAt": "2024-01-16T09:56:29.939Z",
      "StatusResolution": "truePositive",
      "UpdatedAt": "2024-01-16T09:56:29.939Z",
      "Description": "string",
      "SignOfCreation": "auto",
      "Priority": "low"
      "HistoryRecords": [
        {
          "entityID": "string",
          "entityKind": "Alert",
          "tenantID": "string",
          "type": "alertAssigned",
          "createdAt": "2024-03-12T11:11:58.864Z",
          "params": {}
        }
      ]
    }
  ]
}

Possible errors

HTTP code	Description	`message` field value	`details` field value
400	The timestampField value is invalid.	invalid timestamp field
400	The from value is invalid.	cannot parse from	variable
400	The to value is invalid.	cannot parse to	variable
400	The id value is not in the UUID format.
403	The user does not have the required right in the Alerts and incidents functional area in any of the specified tenants.	access denied
500	Any other internal errors.	variable	variable

Page top

Viewing a list of tenants

GET /xdr/api/v1/tenants

Returns the list of tenants for which the user has the Read right.

Example:

https://api.example.com/xdr/api/v1/tenants

Response

HTTP code: 200

Format: JSON

Example:

[
  {
    "ID": "string",
    "Name": "string",
    "Description": "string",
    "Removable": true,
    "Subtenants": [
      "string"
    ],
    "IsRoot": true
  }
]

Possible errors

HTTP code	Description	`message` field value	`details` field value
500	Any other internal errors.	variable	variable

Page top

Closing alerts

POST /xdr/api/v1/alerts/close

Sets the status value to closed for the specified alert.

Example:

https://api.example.com/xdr/api/v1/alerts/close

Request body

Format: JSON

Example:

[
  {
    "ID": "00000000-0000-0000-0000-000000000000",  
    "TenantID": "00000000-0000-0000-0000-000000000000",  
    "Reason": "falsePositive"
  }
]

Name	Data type	Mandatory	Description	Value example
ID	string	Yes	The alert id.	00000000-0000-0000-0000-000000000000
TenantID	string	Yes	The tenant id.	00000000-0000-0000-0000-000000000000
Reason	string	Yes	The reason for closure.	falsePositive lowPriority

Response

HTTP code: 204

If the alert has already been closed with the same reason value, the response code is also 204.

Possible Errors

HTTP code	Description	`message` field value	`details` field value
400	The ID value is not specified.	id required
400	The Reason value is not specified.	reason required
400	The Reason value is invalid.	invalid reason
403	The user does not have the required role in the Alerts and incidents functional area in any of the specified tenants.	access denied
404	The alert with the specified ID is not found.	alert not found
500	Any other internal errors.	variable	variable

Page top

Closing incidents

POST /xdr/api/v1/incidents/close

Sets the status value to closed for the specified incident.

Example:

https://api.example.com/xdr/api/v1/incidents/close

Request body

Format: JSON

Example:

[
  {
    "ID": "00000000-0000-0000-0000-000000000000",  
    "TenantID": "00000000-0000-0000-0000-000000000000",  
    "Reason": "falsePositive"
  }
]

Name	Data type	Mandatory	Description	Value example
ID	string	Yes	The incident id.	00000000-0000-0000-0000-000000000000
TenantID	string	Yes	The tenant id.	00000000-0000-0000-0000-000000000000
Reason	string	Yes	The reason for closure.	truePositive falsePositive lowPriority

Response

HTTP code: 204

If the incident has already been closed with the same reason value, the response code is also 204.

Possible Errors

HTTP code	Description	`message` field value	`details` field value
400	The ID value is not specified.	id required
400	The Reason value is not specified.	reason required
400	The Reason value is invalid.	invalid reason
403	The user does not have the required role in the Alerts and incidents functional area in any of the specified tenants.	access denied
404	The incident with the specified ID is not found.	incident not found
500	Any other internal errors.	variable	variable

Page top

Viewing a list of active lists on the correlator

GET /xdr/api/v2.1/kuma/activeLists/

The target correlator must be running.

Access: Main administrator, Tenant administrator, Tier 2 analyst, Tier 1 analyst.

Query parameters

Name	Data type	Mandatory	Description	Value example
correlatorID	string	Yes	Correlator service ID	00000000-0000-0000-0000-000000000000

Response

HTTP code: 200

Format: JSON

type Response []ActiveListInfo
 
type ActiveListInfo struct {
    ID      string `json:"id"`
    Name    string `json:"name"`
    Dir     string `json:"dir"`
    Records uint64 `json:"records"`
    WALSize uint64 `json:"walSize"`
}

Possible errors

HTTP code	Description	`Message` field value	`Details` field value
400	Correlator service ID is not specified	query parameter required	correlatorID
403	The user does not have the required role in the correlator tenant	access denied	-
404	The service with the specified identifier (correlatorID) was not found	service not found	-
406	The service with the specified ID (correlatorID) is not a correlator	service is not correlator	-
406	The correlator did not execute the first start	service not paired	-
406	The correlator tenant is disabled	tenant disabled	-
50x	Failed to access the correlator API	correlator API request failed	variable
500	Failed to decode the response body received from the correlator	correlator response decode failed	variable
500	Any other internal errors	variable	variable

Page top

Importing entries to an active list

POST /xdr/api/v2.1/kuma/activeLists/import

The target correlator must be running.

Access: Main administrator, Tenant administrator, Tier 2 analyst, Tier 1 analyst.

Query parameters (URL Query)

Name	Data type	Mandatory	Description	Value example
correlatorID	string	Yes	Correlator service ID	00000000-0000-0000-0000-000000000000
activeListID	string	If activeListName is not specified	Active list ID	00000000-0000-0000-0000-000000000000
activeListName	string	If activeListID is not specified	Active list name	Attackers
format	string	Yes	Format of imported entries	CSV, TSV, internal
keyField	string	For the CSV and TSV formats only	The name of the field in the header of the CSV or TSV file that will be used as the key field of the active list record. The values of this field must be unique	ip
clear	bool	No	Clear the active list before importing. If the parameter is present in the URL query, then its value is assumed to be true. The values specified by the user are ignored.	/xdr/api/v2.1/kuma/activeLists/import?clear

Request body

Format	Contents
CSV	The first line is the header, which lists the comma-separated fields. The rest of the lines are the values corresponding to the comma-separated fields in the header. The number of fields in each line must be the same.
TSV	The first line is the header, which lists the TAB-separated fields. The remaining lines are the values corresponding to the TAB-separated fields in the header. The number of fields in each line must be the same.
internal	Each line contains one individual JSON object. Data in the internal format can be received by exporting the contents of the active list from the correlator in the KUMA Console.

Response

HTTP code: 204

Possible errors

HTTP code	Description	`Message` field value	`Details` field value
400	Correlator service ID is not specified	query parameter required	correlatorID
400	Neither the activeListID parameter nor the activeListName parameter is specified	one of query parameters required	activeListID, activeListName
400	The `format` parameter is not specified	query parameter required	format
400	The `format` parameter is invalid	invalid query parameter value	format
400	The `keyField` parameter is not specified	query parameter required	keyField
400	The request body has a zero-length	request body required	-
400	The CSV or TSV file does not contain the field specified in the keyField parameter	correlator API request failed	variable
400	Request body parsing error	correlator API request failed	variable
403	The user does not have the required role in the correlator tenant	access denied	-
404	The service with the specified identifier (correlatorID) was not found	service not found	-
404	No active list was found	active list not found	-
406	The service with the specified ID (`correlatorID`) is not a correlator	service is not correlator	-
406	The correlator did not execute the first start	service not paired	-
406	The correlator tenant is disabled	tenant disabled	-
406	A search was performed using the name of the active list (`activeListName`), and more than one active list was found	more than one matching active lists found	-
50x	Failed to access the correlator API	correlator API request failed	variable
500	Failed to decode the response body received from the correlator	correlator response decode failed	variable
500	Any other internal error	variable	variable

Page top

Searching assets

GET /xdr/api/v2.1/kuma/assets/

Information about the software of assets is not stored in OSMP and is not shown in the response.

Access: Main administrator, Tenant administrator, Tier 2 analyst, Tier 1 analyst, Junior analyst, Access to NCIRCC, Access to CII, Observer.

Query parameters

Name	Data type	Mandatory	Description	Value example
page	number	No	Page number. Starts with 1. The page size is 250 entries. If the parameter is not specified, the default value is 1.	1
id	string	No	Asset ID. If the parameter is specified several times, then a list is generated and the logical OR operator is applied.	00000000-0000-0000-0000-000000000000
tenantID	string	No	Asset tenant ID. If the parameter is specified several times, then a list is generated and the logical OR operator is applied. If the user does not have the required role in the specified tenant, then this tenant is ignored.	00000000-0000-0000-0000-000000000000
name	string	No	Asset name. Case-insensitive regular expression (PCRE).	asset ^My asset$
fqdn	string	No	Asset FQDN. Case-insensitive regular expression (PCRE).	example.com
ip	string	No	Asset IP address. Case-insensitive regular expression (PCRE).	10.10 ^192.168.1.2$
mac	string	No	Asset MAC address. Case-insensitive regular expression (PCRE).	^00:0a:95:9d:68:16$

Response

HTTP code: 200

Format: JSON

type Response []Asset
 
type Asset struct {
    ID                     string               `json:"id"`
    TenantID               string               `json:"tenantID"`
    TenantName             string               `json:"tenantName"`
    Name                   string               `json:"name"`
    FQDN                   []string             `json:"fqdn"`
    IPAddresses            []string             `json:"ipAddresses"`
    MACAddresses           []string             `json:"macAddresses"`
    Owner                  string               `json:"owner"`
    OS                     *OS                  `json:"os"`
    Software               []Software           `json:"software"`
    Vulnerabilities        []Vulnerability      `json:"vulnerabilities"`
    KICSRisks              []*assets.KICSRisk   `json:"kicsVulns"`
    KSC                    *KSCFields           `json:"ksc"`
    Created                string               `json:"created"`
    Updated                string               `json:"updated"`
    CustomFields           []CustomField        `json:"customFields"`
}
 
type KSCFields struct {
    NAgentID          string `json:"nAgentID"`
    KSCInstanceID     string `json:"kscInstanceID"`
    KSCMasterHostname string `json:"kscMasterHostname"`
    LastVisible       string `json:"lastVisible"`
}
 
type OS struct {
    Name    string `json:"name"`
    Version uint64 `json:"version"`
}
 
type Software struct {
    Name    string `json:"name"`
    Version string `json:"version"`
    Vendor  string `json:"vendor"`
}
 
type Vulnerability struct {
    KasperskyID           string   `json:"kasperskyID"`
    ProductName           string   `json:"productName"`
    DescriptionURL        string   `json:"descriptionURL"`
    RecommendedMajorPatch string   `json:"recommendedMajorPatch"`
    RecommendedMinorPatch string   `json:"recommendedMinorPatch"`
    SeverityStr           string   `json:"severityStr"`
    Severity              uint64   `json:"severity"`
    CVE                   []string `json:"cve"`
    ExploitExists         bool     `json:"exploitExists"`
    MalwareExists         bool     `json:"malwareExists"`
}
 
type assets.KICSRisk struct {
    ID             int64   `json:"id"`
    Name           string  `json:"name"`
    Category       string  `json:"category"`
    Description    string  `json:"description"`
    DescriptionUrl string  `json:"descriptionUrl"`
    Severity       int     `json:"severity"`
    Cvss           float64 `json:"cvss"`
}
   
type CustomField struct {
    ID    string `json:"id"`
    Name  string `json:"name"`
    Value string `json:"value"`
}

Possible errors

HTTP code	Description	`Message` field value	`Details` field value
400	Invalid value of the "page" parameter	invalid query parameter value	page
500	Any other internal error	variable	variable

Page top

Importing assets

POST /xdr/api/v2.1/kuma/assets/import

Bulk creation or update of assets.

If the FQDN of an asset is specified, it acts as the unique ID of the asset within the tenant. If the asset name is not specified, either FQDN or the first IP address is used as the name. Assets imported from Kaspersky Security Center cannot be updated, therefore, FQDN conflicts may occur during the import process if a Kaspersky Security Center asset with a the same FQDN already exists in the tenant. Such conflicts prevent the processing of the conflicting asset, but do not prevent the processing of other assets specified in the request body. Allows you to populate custom fields by uuid from the assetsCustomFields settings.

Access: Main administrator, Tenant administrator, Tier 2 analyst, Tier 1 analyst

Request body

Format: JSON

type Request struct {
   TenantID string  `json:"tenantID"`
    Assets   []Asset `json:"assets"`
}
 
type Asset struct {
    Name            string          `json:"name"`
    FQDN            string          `json:"fqdn"`
    IPAddresses     []string        `json:"ipAddresses"`
    MACAddresses    []string        `json:"macAddresses"`
    Owner           string          `json:"owner"`
    OS              *OS             `json:"os"`
    Software        []Software      `json:"software"`
    Vulnerabilities []Vulnerability `json:"vulnerabilities"`
    CustomFields    []CustomField      `json:"customFields"`
}
 
type OS struct {
    Name    string `json:"name"`
    Version uint64 `json:"version"`
}
 
type Software struct {
    Name    string `json:"name"`
    Version string `json:"version"`
    Vendor  string `json:"vendor"`
}
 
type Vulnerability struct {
    KasperskyID           string   `json:"kasperskyID"`
    ProductName           string   `json:"productName"`
    DescriptionURL        string   `json:"descriptionURL"`
    RecommendedMajorPatch string   `json:"recommendedMajorPatch"`
    RecommendedMinorPatch string   `json:"recommendedMinorPatch"`
    SeverityStr           string   `json:"severityStr"`
    Severity              uint64   `json:"severity"`
    CVE                   []string `json:"cve"`
    ExploitExists         bool     `json:"exploitExists"`
    MalwareExists         bool     `json:"malwareExists"`
}
 
type CustomFields struct {
    ID           string   `json:"id"`
    Value        string   `json:"value"`
}

Request mandatory fields

Name	Data type	Mandatory	Description	Value example
tenantID	string	Yes	Tenant ID	00000000-0000-0000-0000-000000000000
assets	[]Asset	Yes	Array of imported assets

Asset mandatory fields

Name

Data type

Mandatory

Description

Value example

fqdn

string

If the ipAddresses array is not specified

Asset FQDN. It is recommended that you specify the FQDN and not just the host name. Priority indicator for asset identification.

[my-asset-1.example.com]

[my-asset-1]

ipAddresses

[]string

If FQDN is not specified

Array of IP addresses for the asset. IPv4 or IPv6. The first element of the array is used as a secondary indicator for asset identification.

["192.168.1.1", "192.168.2.2"]

["2001:0db8:85a3:0000:0000:8a2e:0370:7334"]

Response

HTTP code: 200

Format: JSON

type Response struct {

InsertedIDs map[int64]interface{} `json:"insertedIDs"`

UpdatedCount uint64 `json:"updatedCount"`

Errors []ImportError `json:"errors"`

}

type ImportError struct {

Index uint64 `json:"index"`

Message string `json:"message"`

}

Possible errors

HTTP code	Description	`Message` field value	`Details` field value
400	Tenant ID is not specified	tenantID required	-
400	Attempt to import assets into the shared tenant	import into shared tenant not allowed	-
400	Not a single asset was specified in the request body	at least one asset required	-
400	None of the mandatory fields is specified	one of fields required	asset[<index>]: fqdn, ipAddresses
400	Invalid FQDN	invalid value	asset[<index>].fqdn
400	Invalid IP address	invalid value	asset[<index>].ipAddresses[<index>]
400	IP address is repeated	duplicated value	asset[<index>].ipAddresses
400	Invalid MAC address	invalid value	asset[<index>].macAddresses[<index>]
400	MAC address is repeated	duplicated value	asset[<index>].macAddresses
403	The user does not have the required role in the specified tenant	access denied	-
404	The specified tenant was not found	tenant not found	-
406	The specified tenant was disabled	tenant disabled	-
500	Any other internal error	variable	variable

Page top

Deleting assets

POST /xdr/api/v2.1/kuma/assets/delete

Access: Main administrator, Tenant administrator, Tier 2 analyst, Tier 1 analyst, SOC manager, Access to CII, Approver.

Request body

Format: JSON

Name	Data type	Mandatory	Description	Value example
tenantID	string	Yes	Tenant ID	00000000-0000-0000-0000-000000000000
ids	[]string	If neither the ipAddresses array nor the FQDNs are specified	List of asset IDs	["00000000-0000-0000-0000-000000000000"]
fqdns	[]string	If neither the ipAddresses array nor the IDs are specified	Array of asset FQDNs	["my-asset-1.example.com", "my-asset-1"]
ipAddresses	[]string	If neither the IDs nor FQDNs are specified	Array of main IP addresses of the asset.	["192.168.1.1", "2001:0db8:85a3:0000:0000:8a2e:0370:7334"]

Response

HTTP code: 200

Format: JSON

type Response struct {
    DeletedCount uint64 `json:"deletedCount"`
}

Possible errors

HTTP code	Description	`Message` field value	`Details` field value
400	Tenant ID is not specified	tenantID required	-
400	Attempt to delete an asset from the shared tenant	delete from shared tenant not allowed	-
400	None of the mandatory fields is specified	one of fields required	ids, fqdns, ipAddresses
400	Invalid FQDN specified	invalid value	fqdns[<index>]
400	Invalid IP address specified	invalid value	ipAddresses[<index>]
403	The user does not have the required role in the specified tenant	access denied	-
404	The specified tenant was not found	tenant not found	-
406	The specified tenant was disabled	tenant disabled	-
500	Any other internal error	variable	variable

Page top

Searching events

POST /xdr/api/v2.1/kuma/events/

Only search queries or aggregation queries (SELECT) are allowed.

Access: Main administrator, Tenant administrator, Tier 2 analyst, Tier 1 analyst, Junior analyst, Access to NCIRCC, Access to CII, Observer.

Request body

Format: JSON

Request

Name	Data type	Mandatory	Description	Value example
period	Period	Yes	Search period
sql	string	Yes	SQL query	SELECT * FROM events WHERE Type = 3 ORDER BY Timestamp DESC LIMIT 1000 SELECT sum(BytesOut) as TotalBytesSent, SourceAddress FROM events WHERE DeviceVendor = 'netflow' GROUP BY SourceAddress LIMIT 1000 SELECT count(Timestamp) as TotalEvents FROM events LIMIT 1
clusterID	string	No, if the cluster is the only one	Storage cluster ID. You can find it by requesting a list of services with kind = storage. The cluster ID will be in the resourceID field.	00000000-0000-0000-0000-000000000000
rawTimestamps	bool	No	Display timestamps in their current format—Milliseconds since EPOCH. False by default.	true false
emptyFields	bool	No	Display empty fields for normalized events. False by default.	true false

Period

Name

Data type

Mandatory

Description

Value example

from

string

Yes

Lower bound of the period in RFC3339 format. Timestamp >= <from>

2021-09-06T00:00:00Z (UTC)

2021-09-06T00:00:00.000Z (UTC, including milliseconds)

2021-09-06T00:00:00Z+00:00 (MSK)

string

Yes

Upper bound of the period in RFC3339 format.

Timestamp <= <to>

2021-09-06T00:00:00Z (UTC)

2021-09-06T00:00:00.000Z (UTC, including milliseconds)

2021-09-06T00:00:00Z+00:00 (MSK)

Response

HTTP code: 200

Format: JSON

Result of executing the SQL query

Possible errors

HTTP code	Description	`Message` field value	`Details` field value
400	The lower bounds of the range is not specified	period.from required	-
400	The lower bounds of the range is in an unsupported format	cannot parse period.from	variable
400	The lower bounds of the range is equal to zero	period.from cannot be 0	-
400	The upper bounds of the range is not specified	period.to required	-
400	The upper bounds of the range is in an unsupported format	cannot parse period.to	variable
400	The upper bounds of the range is equal to zero	period.to cannot be 0	-
400	The lower bounds of the range is greater than the upper bounds	period.from cannot be greater than period.to	-
400	Invalid SQL query	invalid sql	variable
400	An invalid table appears in the SQL query	the only valid table is `events`	-
400	The SQL query lacks a LIMIT	sql: LIMIT required	-
400	The LIMIT in the SQL query exceeds the maximum (1000)	sql: maximum LIMIT is 1000	-
404	Storage cluster not found	cluster not found	-
406	The clusterID parameter was not specified, and many clusters were registered	multiple clusters found, please provide clusterID	-
500	No available cluster nodes	no nodes available	-
50x	Any other internal error	event search failed	variable

Page top

Viewing information about the cluster

GET /xdr/api/v2.1/kuma/events/clusters/

Access: The main tenant clusters are accessible to all users.

Query parameters (URL Query)

Name	Data type	Mandatory	Description	Value example
page	number	No	Page number. Starts with 1. The page size is 250 entries. If the parameter is not specified, the default value is 1.	1
id	string	No	Cluster ID. If the parameter is specified several times, then a list is generated and the logical OR operator is applied	00000000-0000-0000-0000-000000000000
tenantID	string	No	Tenant ID. If the parameter is specified several times, then a list is generated and the logical OR operator is applied. If the user does not have the required role in the specified tenant, then this tenant is ignored.	00000000-0000-0000-0000-000000000000
name	string	No	Cluster name. Case-insensitive regular expression (PCRE).	cluster ^My cluster$

Response

HTTP code: 200

Format: JSON

type Response []Cluster
 
type Cluster struct {
    ID         string `json:"id"`
    Name       string `json:"name"`
    TenantID   string `json:"tenantID"`
    TenantName string `json:"tenantName"`
}

Possible errors

HTTP code	Description	`Message` field value	`Details` field value
400	Invalid value of the "page" parameter	invalid query parameter value	page
500	Any other internal error	variable	variable

Page top

Resource search

GET /xdr/api/v2.1/kuma/resources/

Access: Main administrator, Tenant administrator, Tier 2 analyst, Tier 1 analyst, Observer.

Query parameters (URL Query)

Name	Data type	Mandatory	Description	Value example
page	number	No	Page number. Starts with 1. The page size is 250 entries. If the parameter is not specified, the default value is 1.	1
id	string	No	Resource ID. If the parameter is specified several times, then a list is generated and the logical OR operator is applied.	00000000-0000-0000-0000-000000000000
tenantID	string	No	Resource tenant ID. If the parameter is specified several times, then a list is generated and the logical OR operator is applied. If the user does not have the required role in the specified tenant, then this tenant is ignored.	00000000-0000-0000-0000-000000000000
name	string	No	Resource name. Case-insensitive regular expression (PCRE).	resource ^My resource$
kind	string	No	Resource type. If the parameter is specified several times, then a list is generated and the logical OR operator is applied	collector, correlator, storage, activeList, aggregationRule, connector, correlationRule, dictionary, enrichmentRule, destination, filter, normalizer, responseRule, search, agent, proxy, secret
userID	string	No	User ID. If the parameter is specified several times, then a list is generated and the logical OR operator is applied. The me value corresponds to the user that performs the request.	00000000-0000-0000-0000-000000000000 me

Response

HTTP code: 200

Format: JSON

type Response []Resource
 
type Resource struct {
    ID          string `json:"id"`
    Kind        string `json:"kind"`
    Name        string `json:"name"`
    Description string `json:"description"`
    TenantID    string `json:"tenantID"`
    TenantName  string `json:"tenantName"`
    UserID      string `json:"userID"`
    UserName    string `json:"userName"`
    Created     string `json:"created"`
    Updated     string `json:"updated"`
}

Possible errors

HTTP code	Description	`Message` field value	`Details` field value
400	Invalid value of the "page" parameter	invalid query parameter value	page
400	Invalid value of the "kind" parameter	invalid kind	<kind>
500	Any other internal error	variable	variable

Page top

Loading resource file

POST /xdr/api/v2.1/kuma/resources/upload

Access: Main administrator, Tenant administrator, Tier 2 analyst, Tier 1 analyst.

Request body

Encrypted contents of the resource file in binary format.

Response

HTTP code: 200

Format: JSON

File ID. It should be specified in the body of requests for viewing the contents of the file and for importing resources.

type Response struct {
    ID string `json:"id"`
}

Possible errors

HTTP code	Description	`Message` field value	`Details` field value
400	The file size exceeds the maximum allowable (64 MB)	maximum file size is 64 MB	-
403	The user does not have the required roles in any of the tenants	access denied	-
500	Any other internal error	variable	variable

Page top

Viewing the contents of a resource file

POST /xdr/api/v2.1/kuma/resources/toc

Access: Main administrator, Tenant administrator, Tier 2 analyst, Tier 1 analyst.

Request body

Format: JSON

Name	Data type	Mandatory	Description	Value example
fileID	string	Yes	The file ID obtained as a result of loading the resource file.	00000000-0000-0000-0000-000000000000
password	string	Yes	Resource file password.	SomePassword!88

Response

HTTP code: 200

Format: JSON

File version, list of resources, categories, and folders.

The ID of the retrieved resources must be used when importing.

type TOCResponse struct {
    Folders []*Folder `json:"folders"`
}
 
type Folder struct {
    ID          string      `json:"id"`
    TenantID    string      `json:"tenantID"`
    TenantName  string      `json:"tenantName"`
    ExportID    string      `json:"exportID"`
    Kind        string      `json:"kind"`
    SubKind     string      `json:"subKind"`
    Name        string      `json:"name"`
    Description string      `json:"description"`
    UserID      string      `json:"userID"`
    ParentID    string      `json:"parentID"`
    CreatedAt   int64       `json:"createdAt"`
    Resources   []*Resource `json:"resources"`
}
 
type Resource struct {
    ID   string   `json:"id"`
    Kind string   `json:"kind"`
    Name string   `json:"name"`
    Deps []string `json:"deps"`
}

Page top

Importing resources

POST /xdr/api/v2.1/kuma/resources/import

Access: Main administrator, Tenant administrator, Tier 2 analyst, Tier 1 analyst.

Request body

Name

Data type

Mandatory

Description

Value example

fileID

string

Yes

The file ID obtained as a result of loading the resource file.

00000000-0000-0000-0000-000000000000

password

string

Yes

Resource file password.

SomePassword!88

tenantID

string

Yes

ID of the target tenant

00000000-0000-0000-0000-000000000000

actions

map[string]uint8

Yes

Mapping of the resource ID to the action that must be taken in relation to it.

0 – do not import (used when resolving conflicts)

1 – import (should initially be assigned to each resource)

2 – replace (used when resolving conflicts)

{

"00000000-0000-0000-0000-000000000000": 0,

"00000000-0000-0000-0000-000000000001": 1,

"00000000-0000-0000-0000-000000000002": 2,

}

Response

HTTP code

Body

204

409

The imported resources conflict with the existing ones by ID. In this case, you need to repeat the import operation while specifying the following actions for these resources:

0 – do not import

2 – replace

type ImportConflictsError struct {
    HardConflicts []string `json:"conflicts"`
}

Page top

Exporting resources

POST /xdr/api/v2.1/kuma/resources/export

Access: Main administrator, Tenant administrator, Tier 2 analyst, Tier 1 analyst.

Request body

Format: JSON

Name	Data type	Mandatory	Description	Value example
ids	[]string	Yes	Resource IDs to be exported	["00000000-0000-0000-0000-000000000000"]
password	string	Yes	Exported resource file password	SomePassword!88
tenantID	string	Yes	ID of the tenant that owns the exported resources	00000000-0000-0000-0000-000000000000

Response

HTTP code: 200

Format: JSON

ID of the file with the exported resources. It should be used in a request to download the resource file.

type ExportResponse struct {
    FileID string `json:"fileID"`
}

Page top

Downloading the resource file

GET /xdr/api/v2.1/kuma/resources/download/<id>

id is the file ID obtained as a result of executing a resource export request.

Access: Main administrator, Tenant administrator, Tier 2 analyst, Tier 1 analyst.

Response

HTTP code: 200

Encrypted contents of the resource file in binary format.

Possible errors

HTTP code	Description	`Message` field value	`Details` field value
400	File ID not specified	route parameter required	id
400	The file ID is not a valid UUID	id is not a valid UUID	-
403	The user does not have the required roles in any of the tenants	access denied	-
404	File not found	file not found	-
406	The file is a directory	not regular file	-
500	Any other internal error	variable	variable

Page top

Searching services

GET /xdr/api/v2.1/kuma/services/

Access: Main administrator, Tenant administrator, Tier 2 analyst, Tier 1 analyst.

Query parameters (URL Query)

Name	Data type	Mandatory	Description	Value example
page	number	No	Page number. Starts with 1. The page size is 250 entries. If the parameter is not specified, the default value is 1.	1
id	string	No	Service ID. If the parameter is specified several times, then a list is generated and the logical OR operator is applied.	00000000-0000-0000-0000-000000000000
tenantID	string	No	Service tenant ID. If the parameter is specified several times, then a list is generated and the logical OR operator is applied. If the user does not have the required role in the specified tenant, then this tenant is ignored.	00000000-0000-0000-0000-000000000000
name	string	No	Service name. Case-insensitive regular expression (PCRE).	service ^My service$
kind	string	No	Service type. If the parameter is specified several times, then a list is generated and the logical OR operator is applied.	collector, correlator, storage, agent
fqdn	string	No	Service FQDN. Case-insensitive regular expression (PCRE).	hostname ^hostname.example.com$
paired	bool	No	Display only those services that executed the first start. If the parameter is present in the URL query, then its value is assumed to be true. The values specified by the user are ignored.	/xdr/api/v2.1/kuma/services?paired

Response

HTTP code: 200

Format: JSON

type Response []Service
 
type Service struct {
    ID         string `json:"id"`
    TenantID   string `json:"tenantID"`
    TenantName string `json:"tenantName"`
    ResourceID string `json:"resourceID"`
    Kind       string `json:"kind"`
    Name       string `json:"name"`
    Address    string `json:"address"`
    FQDN       string `json:"fqdn"`
    Status     string `json:"status"`
    Warning    string `json:"warning"`
    APIPort    string `json:"apiPort"`
    Uptime     string `json:"uptime"`
    Version    string `json:"version"`
    Created    string `json:"created"`
    Updated    string `json:"updated"`
}

Possible errors

HTTP code	Description	`Message` field value	`Details` field value
400	Invalid value of the "page" parameter	invalid query parameter value	page
400	Invalid value of the "kind" parameter	invalid kind	<kind>
500	Any other internal error	variable	variable

Page top

Viewing token bearer information

GET /xdr/api/v2.1/kuma/users/whoami

Response

The response returns the superior role of all the roles assigned to the user.

HTTP code: 200

Format: JSON

type Tenant struct {
    ID   string `json:"id"`
    Name string `json:"name"`
}
 
type Role struct {
    ID      string   `json:"id"`
    Name    string   `json:"name"`
    Tenants []Tenant `json:"tenants"`
}
 
type Response struct {
    ID    string `json:"id"`
    Name  string `json:"name"`
    Login string `json:"login"`
    Email string `json:"email"`
    Roles []Role `json:"roles"`
}

Page top

Dictionary updating in services

POST /xdr/api/v2.1/kuma/dictionaries/update

You can update only dictionaries in dictionary resources of the table type.

Access: Main administrator, Tenant administrator, Tier 2 analyst, Tier 1 analyst.

Query parameters (URL Query)

Name

Data type

Mandatory

Description

Value example

dictionaryID

string

Yes

ID of the dictionary that will be updated.

00000000-0000-0000-0000-000000000000

needReload

number

Specifies whether to update the parameters of services that use this dictionary:

0 – do not update the service parameters after updating the dictionary.
1 – update the service parameters after updating the dictionary.

Only used if the dictionary's kind is set to dictionary. If the dictionary's kind is set to table, parameters of services that use the dictionary are always updated.

The update affects all services where the specified dictionary is used. If an update in one of the services ends with an error, this does not interrupt updates in the other services.

Request body

Name

Data type

Mandatory

Description

Value example

file

CSV file

Yes

The request contains a CSV file. Data of the existing dictionary is being replaced with data from this file. The first line of the CSV file containing the column names must not be changed.

If the dictionary's kind is set to table, only "key" and "value" columns are allowed.

key columns,column1,column2

key1,k1col1,k1col2

key2,k2col1,k2col2

Response

HTTP code: 200

Format: JSON

type Response struct {
    ServicesFailedToUpdate []UpdateError `json:"servicesFailedToUpdate"`
}
type UpdateError struct {
    ID  string `json:"id"`
    Err error  `json:"err"`
}

Returns only errors for services in which the dictionaries have not been updated.

Possible errors

HTTP code	Description	`Message` field value	`Details` field value
400	Invalid request body	request body decode failed	Error
400	Null count of dictionary lines	request body required	-
400	Dictionary ID not specified	invalid value	dictionaryID
400	Incorrect value of dictionary line	invalid value	rows or rows[i]
400	Dictionary with the specified ID has an invalid type (not table)	can only update table dictionary	-
400	Attempt to change dictionary columns	columns must not change with update	-
403	No access to requested resource	access denied	-
404	Service not found	service not found	-
404	Dictionary not found	dictionary not found	Service ID
500	Any other internal error	variable	variable

Page top

Dictionary retrieval

GET /xdr/api/v2.1/kuma/dictionaries/

You can get only dictionaries in dictionary resources of the table type.

Access: Main administrator, Tenant administrator, Tier 2 analyst, Tier 1 analyst.

Query parameters (URL Query)

Name	Data type	Mandatory	Description	Value example
dictionaryID	string	Yes	ID of the dictionary that will be received	00000000-0000-0000-0000-000000000000

Response

HTTP code: 200

Format: text/plain; charset=utf-8

A CSV file is returned with the dictionary data in the response body.

Page top

Viewing custom fields of the assets

GET /xdr/api/v2.1/kuma/settings/id/:id

The user can view a list of custom fields made by the KUMA user in the application web interface.

A custom field is a bucket for entering text. If necessary, the default value and the mask can be used to validate the entered text in the following format: https://pkg.go.dev/regexp/syntax. All forward slash characters in the mask must be shielded.

Access: Main administrator, Tenant administrator, Tier 2 analyst, Tier 1 analyst, Approver, Observer, Access to NCIRCC, Access to CII.

Query parameters

Name	Data type	Mandatory	Description	Value example
id	string	Yes	Configuration ID of the custom fields	00000000-0000-0000-0000-000000000000

Response

HTTP code: 200

Format: JSON

type Settings struct {
    ID           string         `json:"id"`
    TenantID     string         `json:"tenantID"`
    TenantName   string         `json:"tenantName"`
    Kind         string         `json:"kind"`
    UpdatedAt    int64          `json:"updatedAt"`
    CreatedAt    int64          `json:"createdAt"`
    Disabled     bool           `json:"disabled"`
    CustomFields []*CustomField `json:"customFields"`
}
 
type CustomField struct {
    ID      string `json:"id"`
    Name    string `json:"name"`
    Default string `json:"default"`
    Mask    string `json:"mask"`
}

Possible errors

HTTP code	Description	`Message` field value	`Details` field value
404	Parameters not found: invalid ID or parameters are missing	Not found in database	null
500	Any other internal error	variable	variable

Page top

Viewing the list of context tables in the correlator

GET /xdr/api/v2.1/kuma/contextTables/

The target correlator must be running.

Access: Main administrator, Tenant administrator, Tier 2 analyst, Tier 1 analyst.

Query parameters (URL Query)

Name	Data type	Mandatory	Description	Value example
correlatorID	string	Yes	Correlator service ID	00000000-0000-0000-0000-000000000000

Response

HTTP code: 200

Format: JSON

type Response []ContextTableInfo
 
type ContextTableInfo struct {
    ID      string `json:"id"`
    Name    string `json:"name"`
    Dir     string `json:"dir"`
    Records uint64 `json:"records"`
    WALSize uint64 `json:"walSize"`
}

Possible errors

HTTP code	Description	`Message` field value	`Details` field value
400	Correlator service ID is not specified.	query parameter required	correlatorID
403	The user does not have the required role in the correlator tenant.	access denied	-
404	The service with the specified ID (correlatorID) was not found.	service not found	-
406	The service with the specified ID (correlatorID) is not a correlator.	service is not correlator	-
406	The correlator did not execute the first start.	service not paired	-
406	The tenant of the correlator is disabled.	tenant disabled	-
50x	Failed to gain access to the correlator API.	correlator API request failed	variable
500	Failed to decode the body of the response received from the correlator.	correlator response decode failed	variable
500	Any other internal error.	variable	variable

Page top

Importing records into a context table

POST /xdr/api/v2.1/kuma/contextTables/import

The target correlator must be running.

Access: Main administrator, Tenant administrator, Tier 2 analyst, Tier 1 analyst.

Query parameters (URL Query)

Name	Data type	Mandatory	Description	Value example
correlatorID	string	Yes	Correlator service ID	00000000-0000-0000-0000-000000000000
contextTableID	string	If contextTableName is not specified	Context table ID	00000000-0000-0000-0000-000000000000
contextTableName	string	If contextTableID is not specified	Name of the context table	Attackers
format	string	Yes	Format of imported entries	CSV, TSV, internal
clear	bool	No	Clear the context table before importing. If the parameter is present in the URL query, its value is assumed to be true. The values specified by the user are ignored.	/xdr/api/v2.1/contextTables/import?clear

Request body

Format	Contents
CSV	The first row is the header, which lists the comma-separated fields. The rest of the rows are the comma-separated values corresponding to the fields in the header. The number of fields in each row must be the same, and it must match the number of fields in the schema of the context table. List field values are separated by the "\|" character. For example, the value of a list of integers might be 1\|2\|3.
TSV	The first row is the header, which lists the TAB-separated fields. The rest of the rows are the TAB-separated values corresponding to the fields in the header. The number of fields in each row must be the same, and it must match the number of fields in the schema of the context table. List field values are separated by the "\|" character.
internal	Each line contains one individual JSON object. Data in the 'internal' format can be obtained by exporting the contents of the context table from the correlator in the KUMA Console.

Response

HTTP code: 204

Possible errors

HTTP code	Description	`Message` field value	`Details` field value
400	Correlator service ID is not specified.	query parameter required	correlatorID
400	Neither the contextTableID parameter nor the contextTableName parameter is specified.	one of query parameters required	contextTableID, contextTableName
400	The 'format' parameter is not specified.	query parameter required	format
400	The 'format' parameter is invalid.	invalid query parameter value	format
400	The request body has zero length.	request body required	-
400	Error parsing the request body, including the non-conformance of the field names and types of the record being imported with the schema of the context table.	correlator API request failed	variable
403	The user does not have the required role in the correlator tenant.	access denied	-
404	The service with the specified ID (correlatorID) was not found.	service not found	-
404	The context table was not found.	context table not found	-
406	The service with the specified ID (correlatorID) is not a correlator.	service is not correlator	-
406	The correlator did not execute the first start.	service not paired	-
406	The tenant of the correlator is disabled.	tenant disabled	-
406	More than one context table found by a search for contextTableName.	more than one matching context tables found	-
50x	Failed to gain access to the correlator API.	correlator API request failed	variable
500	Error preparing data for importing into the correlator service.	context table process import request failed	variable
500	Any other internal error.	variable	variable

Page top

Exporting records from a context table

GET /xdr/api/v2.1/kuma/contextTables/export

The target correlator must be running.

Access: Main administrator, Tenant administrator, Tier 2 analyst, Tier 1 analyst.

Query parameters (URL Query)

Name	Data type	Mandatory	Description	Value example
correlatorID	string	Yes	Correlator service ID	00000000-0000-0000-0000-000000000000
contextTableID	string	If contextTableName is not specified	Context table ID	00000000-0000-0000-0000-000000000000
contextTableName	string	If contextTableID is not specified	Name of the context table	Attackers

Response

HTTP code: 200

Format: application/octet-stream

Body: exported context table data, in the 'internal' format: each row contains one individual JSON object.

Possible errors

HTTP code	Description	`Message` field value	`Details` field value
400	Correlator service ID is not specified.	query parameter required	correlatorID
400	Neither the contextTableID parameter nor the contextTableName parameter is specified.	one of query parameters required	contextTableID, contextTableName
403	The user does not have the required role in the correlator tenant.	access denied	-
404	The service with the specified ID (correlatorID) was not found.	service not found	-
404	The context table was not found.	context table not found	-
406	The service with the specified ID (correlatorID) is not a correlator.	service is not correlator	-
406	The correlator did not execute the first start.	service not paired	-
406	The tenant of the correlator is disabled.	tenant disabled	-
406	More than one context table found by a search for contextTableName.	more than one matching context tables found	-
50x	Failed to gain access to the correlator API.	correlator API request failed	variable
500	Any other internal error.	variable	variable

Page top

Viewing a list of aggregation rules

GET /xdr/api/v1/aggregator/<tenantID>/rules

Returns a list of rules that combine events in alerts for the specified tenant.

Query parameters

Name

Data type

Mandatory

Description

Value example

tenantID

string

Yes

The tenant id.

If the user does not have the Read right for the specified tenants, the query fails.

00000000-0000-0000-0000-000000000000

Response

HTTP code: 200

Format: JSON

Example:


[ {"TenantID":"{tenantID}", "ID":"1", "Name": "name1", "Priority": 0, ...}, {"TenantID":"{tenantID}", "ID":"2", "Name": "name2", "Priority": 1, ...}, ]
Name	Data type	Description	Value example
id	string	Rule ID (UUID). The identifier of the default rule is 8e5405a7-6740-471f-a15d-9f9414974060	00000000-0000-0000-0000-000000000000
name	string	Rule name.	Rule1
description	string	Rule description	Aggregate by rule id
tenantID	string	Tenant ID (UUID)	00000000-0000-0000-0000-000000000000
enabled	boolean	Specifies whether to enable the rule.	Yes
trigger	string	Rule trigger. A JQ expression that must return a boolean value.	any(.Observables[]? \| select(.Type == "username") \| .Value; . == "Alice" or . == "Bob")
aggregationID	string	Rule aggregation ID. A JQ expression that must return a string value.	PentestByUserName
alertName	string	The name of the incident. A JQ expression that must return a string value. In the example on the right, the rule name is from the first aggregated event. Subsequently aggregated events do not affect the resulting alert name.	"[PentestByUserName] " + ([.Rules[]?.Name] \| join(","))
aggregationInterval	object: value, int32, minimum is 1 unit: seconds, minutes	The searching interval (30 seconds by default).	45
maxAlertsInAggregate	integer	Maximum number of alerts for aggregation. Minimum is 1. Maximum is 100.	10
priority	integer	Rule priority.	2

Possible errors

HTTP code	Description	`message` field value	`details` field value
500	Any other internal errors.	variable	variable

Page top

Creating an aggregation rule

POST /xdr/api/v1/aggregator/<tenantID>/rules/

Creates a new aggregation rule and adds it to the specified tenant.

Query parameters

Name

Data type

Mandatory

Description

Value example

tenantID

string

Yes

The tenant id.

If the user does not have the Read right for the specified tenant, the query fails.

00000000-0000-0000-0000-000000000000

Request body

Format: JSON

A new rule to add.

{"TenantID":"{tenantID}", "ID":"2", "Name": "newRule1", "Priority": 1, ...}

Name	Data type	Mandatory	Description	Value example
id	string	No	Rule ID (UUID). The identifier of the default rule is 8e5405a7-6740-471f-a15d-9f9414974060	00000000-0000-0000-0000-000000000000
name	string	Yes	Rule name.	Rule1
description	string	No	Rule description	Aggregate by rule id
tenantID	string	Yes	Tenant ID (UUID)	00000000-0000-0000-0000-000000000000
enabled	boolean	Yes	Specifies whether to enable the rule.	Yes
trigger	string	Yes	Rule trigger. A JQ expression that must return a boolean value.	any(.Observables[]? \| select(.Type == "username") \| .Value; . == "Alice" or . == "Bob")
aggregationID	string	Yes	Rule aggregation ID. A JQ expression that must return a string value.	PentestByUserName
alertName	string	Yes	The name of the alert. A JQ expression that must return a string value. In the example on the right, the rule name is from the first aggregated event. Subsequently aggregated events do not affect the resulting alert name.	"[PentestByUserName] " + ([.Rules[]?.Name] \| join(","))
aggregationInterval	object: value, int32, minimum is 1 unit: seconds, minutes	No	The searching interval (30 seconds by default).	45
maxAlertsInAggregate	integer	No	Maximum number of alerts for aggregation. Minimum is 1. Maximum is 100.	10
priority	integer	No	Rule priority.	2

Response

HTTP code: 200

Format: JSON

Returns the ID of the created rule.

Possible errors

HTTP code	Description	`message` field value	`details` field value
400	A rule with the specified name already exists.	variable	variable

Page top

Replacing aggregation rules

PUT /xdr/api/v1/aggregator/<tenantID>/rules/

Replaces aggregation rules for the specified tenant.

To edit existing aggregation rules for a tenant:

Use the GET /xdr/api/v1/aggregator/<tenantID>/rules/ method to obtain current rules.
Edit the obtained rules file.
Use PUT /xdr/api/v1/aggregator/<tenantID>/rules/ to apply edited rules to the tenant.

Query parameters

Name

Data type

Mandatory

Description

Value example

tenantID

string

Yes

The tenant id.

If the user does not have the Read right for the specified tenant, the query fails.

00000000-0000-0000-0000-000000000000

Request body

Format: JSON

An array of rules.

[
    {"TenantID":"{tenantID}", "ID":"2", "Name": "changedName", "Priority": 1, ...},
    {"TenantID":"{tenantID}", "ID":"3", "Name": "name3", "Priority": 2, ...}
]

Name	Data type	Mandatory	Description	Value example
id	string	No	Rule ID (UUID). The identifier of the default rule is 8e5405a7-6740-471f-a15d-9f9414974060	00000000-0000-0000-0000-000000000000
name	string	Yes	Rule name.	Rule1
description	string	No	Rule description	Aggregate by rule id
tenantID	string	Yes	Tenant ID (UUID)	00000000-0000-0000-0000-000000000000
enabled	boolean	Yes	Specifies whether to enable the rule.	Yes
trigger	string	Yes	Rule trigger. A JQ expression that must return a boolean value.	any(.Observables[]? \| select(.Type == "username") \| .Value; . == "Alice" or . == "Bob")
aggregationID	string	Yes	Rule aggregation ID. A JQ expression that must return a string value.	PentestByUserName
alertName	string	Yes	The name of the alert. A JQ expression that must return a string value. In the example on the right, the rule name is from the first aggregated event. Subsequently aggregated events do not affect the resulting alert name.	"[PentestByUserName] " + ([.Rules[]?.Name] \| join(","))
aggregationInterval	object: value, int32, minimum is 1 unit: seconds, minutes	No	The searching interval (30 seconds by default).	45
maxAlertsInAggregate	integer	No	Maximum number of alerts for aggregation. Minimum is 1. Maximum is 100.	10
priority	integer	No	Rule priority. The lower the number you specify, the higher the priority of the rule.	2

If you want to obtain alerts without the default 30-second delay, you can set the aggregationInterval parameter to the value less than 30 or set the maxAlertsInAggregate to the minimum value of 1.

Possible errors

HTTP code	Description	`message` field value	`details` field value
204	The specified JSON file with rules is empty.	variable	variable
400	Bad request.	variable	variable
409	The specified JSON file contains rules with duplicate names.	variable	variable

Page top

Contents

API operations

Viewing a list of alerts

Viewing a list of incidents

Viewing a list of tenants

Closing alerts

Closing incidents

Viewing a list of active lists on the correlator

Importing entries to an active list

Searching assets

Importing assets

Deleting assets

Searching events

Viewing information about the cluster

Resource search

Loading resource file

Viewing the contents of a resource file

Importing resources

Exporting resources

Downloading the resource file

Searching services

Viewing token bearer information

Dictionary updating in services

Dictionary retrieval

Viewing custom fields of the assets

Viewing the list of context tables in the correlator

Importing records into a context table

Exporting records from a context table

Viewing a list of aggregation rules

Creating an aggregation rule

Replacing aggregation rules