Имя	Тип данных	Обязательный	Описание	Пример значения
correlatorID	string	Да	Идентификатор сервиса коррелятора	00000000-0000-0000-0000-000000000000

Ответ

HTTP-код: 200

Формат: 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"`

}

Возможные ошибки

HTTP-код	Описание	Значение поля message	Значение поля details
400	Не указан идентификатор сервиса коррелятора	query parameter required	correlatorID
403	Пользователь не имеет необходимой роли в тенанте коррелятора	access denied
404	Сервис с указанным идентификатором (correlatorID) не найден	service not found
406	Сервис с указанным идентификатором (correlatorID) не является коррелятором	service is not correlator
406	Коррелятор не выполнил первый старт	service not paired
406	Тенант коррелятора отключен	tenant disabled
50x	Не удалось обратиться к API коррелятора	correlator API request failed	вариативное
500	Не удалось декодировать тело ответа, полученное от коррелятора	correlator response decode failed	вариативное
500	Любые другие внутренние ошибки	вариативное	вариативное

В начало

Импорт записей в активный лист

POST /api/v1/activeLists/import

Целевой коррелятор должен быть запущен.

Доступ: администратор, аналитик.

Параметры запроса

Имя	Тип данных	Обязательный	Описание	Пример значения
correlatorID	string	Да	Идентификатор сервиса коррелятора	00000000-0000-0000-0000-000000000000
activeListID	string	Если не указан activeListName	Идентификатор активного листа	00000000-0000-0000-0000-000000000000
activeListName	string	Если не указан activeListID	Имя активного листа	Attackers
format	string	Да	Формат импортируемых записей	csv, tsv, internal
keyField	string	Только для форматов csv и tsv	Имя поля в заголовке csv или tsv файла, которое будет использовано в качестве ключевого поля записи активного листа. Значения этого поля должны быть уникальными	ip
clear	bool	Нет	Очистить активный лист перед выполнением импорта. Если параметр присутствует в URL query, его значение принимается за true. Указанные пользователем значения игнорируются. Пример: /api/v1/activeLists/import?clear

Тело запроса

Формат	Содержимое
csv	Первая строка – заголовок, где перечислены поля, разделенные запятой. Остальные строки – значения, соответствующие полям в заголовке, разделенные запятой. Количество полей на каждой строке должно быть одинаковым.
tsv	Первая строка – заголовок, где перечислены поля, разделенные TAB. Остальные строки – значения, соответствующие полям в заголовке, разделенные TAB. Количество полей на каждой строке должно быть одинаковым.
internal	Каждая строка содержит один индивидуальный объект JSON. Данные в internal формате можно получить путем экспорта содержимого активного листа из коррелятора в WEB-консоли KUMA.

Ответ

HTTP-код: 204

Возможные ошибки

HTTP-код	Описание	Значение поля message	Значение поля details
400	Не указан идентификатор сервиса коррелятора	query parameter required	correlatorID
400	Не указан ни параметр activeListID, ни параметр activeListName	one of query parameters required	activeListID, activeListName
400	Не указан параметр format	query parameter required	format
400	Параметр format имеет неверное значение	invalid query parameter value	format
400	Параметр keyField не задан	query parameter required	keyField
400	Тело запроса имеет нулевую длину	request body required
400	CSV или TSV файл не содержит поле, указанное в параметре keyField	correlator API request failed	line 1: header does not contain column <name>
400	Ошибка парсинга тела запроса	correlator API request failed	line <number>: <message>
403	Пользователь не имеет необходимой роли в тенанте коррелятора	access denied
404	Сервис с указанным идентификатором (correlatorID) не найден	service not found
404	Активный лист не найден	active list not found
406	Сервис с указанным идентификатором (correlatorID) не является коррелятором	service is not correlator
406	Коррелятор не выполнил первый старт	service not paired
406	Тенант коррелятора отключен	tenant disabled
406	Поиск активного листа выполнялся по имени (activeListName) и было найдено более одного активного листа	more than one matching active lists found
50x	Не удалось обратиться к API коррелятора	correlator API request failed	вариативное
500	Не удалось декодировать тело ответа, полученное от коррелятора	correlator response decode failed	вариативное
500	Любые другие внутренние ошибки	вариативное	вариативное

В начало

Поиск алертов

GET /api/v1/alerts

Доступ: администратор, аналитик, оператор.

Параметры запроса

Имя	Тип данных	Обязательный	Описание	Пример значения
page	number	Нет	Номер страницы. Начинается с 1. Размер страницы – 250 записей. Если параметр не указан, то используется значение по умолчанию – 1.	1
id	string	Нет	Идентификатор алерта. Если параметр указан несколько раз, то формируется список и применяется логический оператор ИЛИ.	00000000-0000-0000-0000-000000000000
tenantID	string	Нет	Идентификатор тенанта алерта. Если параметр указан несколько раз, то формируется список и применяется логический оператор ИЛИ. Если пользователь не имеет необходимой роли в указанном тенанте, то данный тенант игнорируется.	00000000-0000-0000-0000-000000000000
name	string	Нет	Имя алерта. Регистронезависимое регулярное выражение (PCRE).	alert ^My alert$
timestampField	string	Нет	Имя поля алерта, по которому выполняется сортировка (DESC) и поиск по периоду (from – to). По умолчанию lastSeen.	lastSeen, firstSeen
from	string	Нет	Нижняя границы периода в формате RFC3339. <timestampField> >= <from>	2021-09-06T00:00:00Z (UTC) 2021-09-06T00:00:00.000Z (UTC, с указанием миллисекунд) 2021-09-06T00:00:00Z+00:00 (MSK)
to	string	Нет	Верхняя периода в формате RFC3339. <timestampField> <= <to>	2021-09-06T00:00:00Z (UTC) 2021-09-06T00:00:00.000Z (UTC, с указанием миллисекунд) 2021-09-06T00:00:00Z+00:00 (MSK)
status	string	Нет	Статус алерта. Если параметр указан несколько раз, то формируется список и применяется логический оператор ИЛИ.	new, assigned, escalated, closed
withEvents	bool	Нет	Включить в ответ нормализованные события KUMA, связанные с найденными алертами. Если параметр присутствует в URL query, его значение принимается за true. Указанные пользователем значения игнорируются. Пример: /api/v1/alerts?withEvents
withAffected	bool	Нет	Включить в ответ информацию об активах и аккаунтах, связанных с найденными алертами. Если параметр присутствует в URL query, его значение принимается за true. Указанные пользователем значения игнорируются. Пример: /api/v1/alerts?withAffected

Ответ

HTTP-код: 200

Формат: JSON

type Response []Alert

type Alert struct {

ID string `json:"id"`

TenantID string `json:"tenantID"`

TenantName string `json:"tenantName"`

Name string `json:"name"`

CorrelationRuleID string `json:"correlationRuleID"`

Priority string `json:"priority"`

Status string `json:"status"`

FirstSeen string `json:"firstSeen"`

LastSeen string `json:"lastSeen"`

Assignee string `json:"assignee"`

ClosingReason string `json:"closingReason"`

Overflow bool `json:"overflow"`

Events []NormalizedEvent `json:"events"`

AffectedAssets []AffectedAsset `json:"affectedAssets"`

AffectedAccounts []AffectedAccount `json:"affectedAccounts"`

}

type NormalizedEvent map[string]interface{}

type AffectedAsset 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"`

KSC *KSCFields `json:"ksc"`

Created string `json:"created"`

Updated string `json:"updated"`

}

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 AffectedAccount struct {

Name string `json:"displayName"`

CN string `json:"cn"`

DN string `json:"dn"`

UPN string `json:"upn"`

SAMAccountName string `json:"sAMAccountName"`

Company string `json:"company"`

Department string `json:"department"`

Created string `json:"created"`

Updated string `json:"updated"`

}

Возможные ошибки

HTTP-код	Описание	Значение поля message	Значение поля details
400	Неверное значение параметра page	invalid query parameter value	page
400	Неверное значение параметра status	invalid status	<status>
400	Неверное значение параметра timestampField	invalid timestamp field
400	Неверное значение параметра from	cannot parse from	вариативное
400	Неверное значение параметра to	cannot parse to	вариативное
400	Значение параметра from больше значения параметра to	from cannot be greater than to
500	Любые другие внутренние ошибки	вариативное	вариативное

В начало

Закрытие алертов

POST /api/v1/alerts/close

Целевой коррелятор должен быть запущен.

Доступ: администратор, аналитик, оператор.

Тело запроса

Формат: JSON

Имя	Тип данных	Обязательный	Описание	Пример значения
id	string	Да	Идентификатор алерта	00000000-0000-0000-0000-000000000000
reason	string	Да	Причина закрытия алерта	responded, incorrect data, incorrect correlation rule

Ответ

HTTP-код: 204

Возможные ошибки

HTTP-код	Описание	Значение поля message	Значение поля details
400	Не указан идентификатор алерта (id)	id required
400	Не указана причина закрытия алерта (reason)	reason required
400	Неверное значение параметра reason	invalid reason
403	Пользователь не имеет необходимой роли в тенанте алерта	access denied
404	Алерт не найден	alert not found
406	Тенант алерта отключен	tenant disabled
406	Алерт уже закрыт	alert already closed
500	Любые другие внутренние ошибки	вариативное	вариативное

В начало

Поиск активов

GET /api/v1/assets

Доступ: администратор, аналитик, оператор.

Параметры запроса

Имя	Тип данных	Обязательный	Описание	Пример значения
page	number	Нет	Номер страницы. Начинается с 1. Размер страницы – 250 записей. Если параметр не указан, то используется значение по умолчанию – 1.	1
id	string	Нет	Идентификатор актива. Если параметр указан несколько раз, то формируется список и применяется логический оператор ИЛИ.	00000000-0000-0000-0000-000000000000
tenantID	string	Нет	Идентификатор тенанта актива. Если параметр указан несколько раз, то формируется список и применяется логический оператор ИЛИ. Если пользователь не имеет необходимой роли в указанном тенанте, то данный тенант игнорируется.	00000000-0000-0000-0000-000000000000
name	string	Нет	Название актива. Регистронезависимое регулярное выражение (PCRE).	asset ^My asset$
fqdn	string	Нет	FQDN актива. Регистронезависимое регулярное выражение (PCRE).	^com$
ip	string	Нет	IP-адрес актива. Регистронезависимое регулярное выражение (PCRE).	10.10 ^192.168.1.2$
mac	string	Нет	MAC-адрес актива. Регистронезависимое регулярное выражение (PCRE).	^00:0a:95:9d:68:16$

Ответ

HTTP-код: 200

Формат: 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"`

KSC *KSCFields `json:"ksc"`

Created string `json:"created"`

Updated string `json:"updated"`

}

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"`

}

Возможные ошибки

HTTP-код	Описание	Значение поля message	Значение поля details
400	Неверное значение параметра page	invalid query parameter value	page
500	Любые другие внутренние ошибки	вариативное	вариативное

В начало

Импорт активов

Особенности идентификации, создания и обновления активов

Активы импортируются в соответствии с правилами слияния данных об активах.

POST /api/v1/assets/import

Массовое создание или обновление активов.

Доступ: администратор, аналитик.

Тело запроса

Формат: 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"`

}

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"`

}

Обязательные поля Request

Имя	Тип данных	Обязательный	Описание	Пример значения
tenantID	string	Да	Идентификатор тенанта	00000000-0000-0000-0000-000000000000
assets	[]Asset	Да	Массив импортируемых активов

Обязательные поля Asset

Имя

Тип данных

Обязательный

Описание

Пример значения

fqdn

string

Если не указан ipAddresses

FQDN актива. Рекомендуется указывать именно FQDN, а не просто имя хоста. Приоритетный признак для идентификации актива.

my-asset-1.example.com

my-asset-1

ipAddresses

[]string

Если не указан fqdn

Массив IP-адресов актива. IPv4 или IPv6. Первый элемент массива используется как второстепенный признак для идентификации актива.

["192.168.1.1", "192.168.2.2"]

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

Ответ

HTTP-код: 200

Формат: 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"`

}

Возможные ошибки

HTTP-код	Описание	Значение поля message	Значение поля details
400	Не указан идентификатор тенанта (tenantID)	tenantID required
400	Попытка импорта активов в общий тенант	import into shared tenant not allowed
400	В теле запроса не указан ни один актив	at least one asset required
400	Не указано ни одно из обязательных полей	one of fields required	asset[<index>]: fqdn, ipAddresses
400	Неверный FQDN	invalid value	asset[<index>].fqdn
400	Неверный IP address	invalid value	asset[<index>].ipAddresses[<index>]
400	Дублируется IP адрес	duplicated value	asset[<index>].ipAddresses
400	Неверный MAC адрес	invalid value	asset[<index>].macAddresses[<index>]
400	Дублируется MAC адрес	duplicated value	asset[<index>].macAddresses
403	Пользователь не имеет необходимой роли в указанном тенанте	access denied
404	Указанный тенант не найден	tenant not found
406	Указанный тенант отключен	tenant disabled
500	Любые другие внутренние ошибки	вариативное	вариативное

В начало

Удаление активов

POST /api/v1/assets/delete

Доступ: администратор, аналитик.

Тело запроса

Формат: JSON

Имя	Тип данных	Обязательный	Описание	Пример значения
tenantID	string	Да	Идентификатор тенанта	00000000-0000-0000-0000-000000000000
ids	[]string	Если не указаны ни fqdns, ни ipAddresses	Список идентификаторов активов	["00000000-0000-0000-0000-000000000000"]
fqdns	[]string	Если не указаны ни ids, ни ipAddresses	Массив FQDN активов	["my-asset-1.example.com", "my-asset-1"]
ipAddresses	[]string	Если не указаны ни ids, ни fqdns	Массив основных IP-адресов активов	["192.168.1.1", "2001:0db8:85a3:0000:0000:8a2e:0370:7334"]

Ответ

HTTP-код: 200

Формат: JSON

type Response struct {

DeletedCount uint64 `json:"deletedCount"`

}

Возможные ошибки

HTTP-код	Описание	Значение поля message	Значение поля details
400	Не указан идентификатор тенанта (tenantID)	tenantID required
400	Попытка удаления актива из общего тенанта	delete from shared tenant not allowed
400	Не указано ни одно из обязательных полей	one of fields required	ids, fqdns, ipAddresses
400	Указан неверный FQDN	invalid value	fqdns[<index>]
400	Указан неверный IP адрес	invalid value	ipAddresses[<index>]
403	Пользователь не имеет необходимой роли в указанном тенанте	access denied
404	Указанный тенант не найден	tenant not found
406	Указанный тенант отключен	tenant disabled
500	Любые другие внутренние ошибки	вариативное	вариативное

В начало

Поиск событий

POST /api/v1/events

Доступ: администратор, аналитик, оператор.

Тело запроса

Формат: JSON

Request

Имя	Тип данных	Обязательный	Описание	Пример значения
period	Period	Да	Период поиска
sql	string	Да	SQL запрос	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	Нет, если кластер единственный	Идентификатор Storage кластера. Можно найти запросив список сервисов с kind = storage. Идентификатор кластера будет в поле resourceID.	00000000-0000-0000-0000-000000000000
rawTimestamps	bool	Нет	Отображать timestamp'ы в исходном виде - Milliseconds since EPOCH. По умолчанию false.	true или false
emptyFields	bool	Нет	Отображать пустые поля нормализованных событий. По умолчанию false.	true или false

Period

Имя

Тип данных

Обязательный

Описание

Пример значения

from

string

Да

Нижняя граница периода в формате RFC3339. Timestamp >= <from>

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

2021-09-06T00:00:00.000Z (UTC, с указанием миллисекунд)

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

to

string

Да

Верхняя граница периода в формате RFC3339.

Timestamp <= <to>

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

2021-09-06T00:00:00.000Z (UTC, с указанием миллисекунд)

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

Ответ

HTTP-код: 200

Формат: JSON

Результат выполнения SQL-запроса

Возможные ошибки

HTTP-код	Описание	Значение поля message	Значение поля details
400	Нижняя граница диапазона не указана	period.from required
400	Нижняя граница диапазона указана в неподдерживаемом формате	cannot parse period.from	вариативное
400	Нижняя граница диапазона равна нулю	period.from cannot be 0
400	Верхняя граница диапазона не указана	period.to required
400	Верхняя граница диапазона указана в неподдерживаемом формате	cannot parse period.to	вариативное
400	Верхняя граница диапазона равна нулю	period.to cannot be 0
400	Нижняя граница диапазона больше верхней	period.from cannot be greater than period.to
400	Неверный SQL запрос	invalid sql	вариативное
400	В SQL запросе фигурирует неверная таблица	the only valid table is `events`
400	В SQL запросе отсутствует LIMIT	sql: LIMIT required
400	LIMIT в SQL запросе превышает максимальный (1000)	sql: maximum LIMIT is 1000
404	Storage cluster не найден	cluster not found
406	Параметр clusterID не был указан и в KUMA зарегистрировано множество кластеров	multiple clusters found, please provide clusterID
500	Нет доступных нод кластера	no nodes available
50x	Любые другие внутренние ошибки	event search failed	вариативное

В начало

Просмотр информации о кластере

GET /api/v1/events/clusters

Доступ: администратор, аналитик, оператор.

Кластеры главного тенанта доступны всем пользователям.

Параметры запроса (URL Query)

Имя	Тип данных	Обязательный	Описание	Пример значения
page	number	Нет	Номер страницы. Начинается с 1. Размер страницы – 250 записей. Если параметр не указан, то используется значение по умолчанию – 1.	1
id	string	Нет	Идентификатор кластера. Если параметр указан несколько раз, то формируется список и применяется логический оператор ИЛИ	00000000-0000-0000-0000-000000000000
tenantID	string	Нет	Идентификатор тенанта. Если параметр указан несколько раз, то формируется список и применяется логический оператор ИЛИ. Если пользователь не имеет необходимой роли в указанном тенанте, то данный тенант игнорируется.	00000000-0000-0000-0000-000000000000
name	string	Нет	Имя кластера. Регистронезависимое регулярное выражение (PCRE).	cluster ^My cluster$

Ответ

HTTP-код: 200

Формат: JSON

type Response []Cluster

type Cluster struct {

ID string `json:"id"`

Name string `json:"name"`

TenantID string `json:"tenantID"`

TenantName string `json:"tenantName"`

}

Возможные ошибки

HTTP-код	Описание	Значение поля message	Значение поля details
400	Неверное значение параметра page	invalid query parameter value	page
500	Любые другие внутренние ошибки	вариативное	вариативное

В начало

Поиск ресурсов

GET /api/v1/resources

Доступ: администратор, аналитик, оператор.

Параметры запроса (URL Query)

Имя	Тип данных	Обязательный	Описание	Пример значения
page	number	Нет	Номер страницы. Начинается с 1. Размер страницы – 250 записей. Если параметр не указан, то используется значение по умолчанию – 1.	1
id	string	Нет	Идентификатор ресурса. Если параметр указан несколько раз, то формируется список и применяется логический оператор ИЛИ.	00000000-0000-0000-0000-000000000000
tenantID	string	Нет	Идентификатор тенанта ресурса. Если параметр указан несколько раз, то формируется список и применяется логический оператор ИЛИ. Если пользователь не имеет необходимой роли в указанном тенанте, то данный тенант игнорируется.	00000000-0000-0000-0000-000000000000
name	string	Нет	Имя ресурса. Регистронезависимое регулярное выражение (PCRE).	resource ^My resource$
kind	string	Нет	Тип ресурса. Если параметр указан несколько раз, то формируется список и применяется логический оператор ИЛИ	collector, correlator, storage, activeList, aggregationRule, connector, correlationRule, dictionary, enrichmentRule, destination, filter, normalizer, responseRule, search, agent, proxy, secret

Ответ

HTTP-код: 200

Формат: 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"`

}

Возможные ошибки

HTTP-код	Описание	Значение поля message	Значение поля details
400	Неверное значение параметра page	invalid query parameter value	page
400	Неверное значение параметр kind	invalid kind	<kind>
500	Любые другие внутренние ошибки	вариативное	вариативное

В начало

Загрузка файла с ресурсами

POST /api/v1/resources/upload

Доступ: администратор, аналитик.

Тело запроса

Зашифрованное содержимое файла с ресурсами в бинарном формате.

Ответ

HTTP-код: 200

Формат: JSON

Идентификатор файла. Следует указать его в теле запросов на просмотр содержимого файла и на импорт ресурсов.

type Response struct {

ID string `json:"id"`

}

Возможные ошибки

HTTP-код	Описание	Значение поля message	Значение поля details
400	Размер файла превышает максимально допустимый (64 МБ)	maximum file size is 64 MB
403	Пользователь не имеет необходимых ролей ни в одном из тенантов	access denied
500	Любые другие внутренние ошибки	вариативное	вариативное

В начало

Просмотр содержимого файла с ресурсами

POST /api/v1/resources/toc

Доступ: администратор, аналитик, оператор.

Тело запроса

Формат: JSON

Имя	Тип данных	Обязательный	Описание	Пример значения
fileID	string	Да	Идентификатор файла, полученный в результате выполнения загрузки файла с ресурсами.	00000000-0000-0000-0000-000000000000
password	string	Да	Пароль файла с ресурсами.	SomePassword!88

Ответ

HTTP-код: 200

Формат: JSON

Версия файла, список ресурсов, категорий, папок.

Идентификатор полученных ресурсов необходимо использовать при импорте.

type Package struct {

Version string `json:"version"`

AssetCategories []*categories.Category `json:"assetCategories"`

Folders []*folders.Folder `json:"folders"`

Resources []*resources.ExportedResource `json:"resources"`

}

В начало

Импорт ресурсов

POST /api/v1/resources/import

Доступ: администратор, аналитик.

Тело запроса

Имя

Тип данных

Обязательный

Описание

Пример значения

fileID

string

Да

Идентификатор файла, полученный в результате выполнения загрузки файла с ресурсами.

00000000-0000-0000-0000-000000000000

password

string

Да

Пароль файла с ресурсами.

SomePassword!88

tenantID

string

Да

Идентификтор целевого тенанта

00000000-0000-0000-0000-000000000000

actions

map[string]uint8

Да

Маппинг идентификатора ресурса к действию, которое нужно предпринять в отношении него.

0 – не импортировать (используется при разрешении конфликтов)

1 – импортировать (изначально должно быть присвоено каждому ресурсу)

2 – заменить (используется при разрешении конфликтов)

{

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

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

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

}

Ответ

HTTP-код

Тело

204

409

Идентификаторы импортируемых ресурсов, конфликтующих с уже существующими по ID. В этом случае необходимо повторить операцию импорта, указав для данных ресурсов следующие действия:

0 – не импортировать

2 – заменить

type ImportConflictsError struct {

HardConflicts []string `json:"conflicts"`

}

В начало

Экспорт ресурсов

POST /api/v1/resources/export

Доступ: администратор, аналитик.

Тело запроса

Формат: JSON

Имя	Тип данных	Обязательный	Описание	Пример значения
ids	[]string	Да	Идентификаторы ресурсов, которые необходимо экспортировать	["00000000-0000-0000-0000-000000000000"]
password	string	Да	Пароль файла с экспортированными ресурсами	SomePassword!88
tenantID	string	Да	Идентификатор тенанта, которому принадлежат экспортируемые ресурсы	00000000-0000-0000-0000-000000000000

Ответ

HTTP-код: 200

Формат: JSON

Идентификатор файла с экспортированными ресурсами. Следует использовать его в запросе на скачивание файла с ресурсами.

type ExportResponse struct {

FileID string `json:"fileID"`

}

В начало

Скачивание файла с ресурсами

GET /api/v1/resources/download/<id>

Здесь id – идентификатор файла, полученный в результате выполнения запроса на экспорт ресурсов.

Доступ: администратор, аналитик.

Ответ

HTTP-код: 200

Зашифрованное содержимое файла с ресурсами в бинарном формате.

Возможные ошибки

HTTP-код	Описание	Значение поля message	Значение поля details
400	Не указан идентификатор файла	route parameter required	id
400	Идентификатор файла не является валидным UUID	id is not a valid UUID
403	Пользователь не имеет необходимых ролей ни в одном из тенантов	access denied
404	Файл не найден	file not found
406	Файл является директорией	not regular file
500	Любые другие внутренние ошибки	вариативное	вариативное

В начало

Поиск сервисов

GET /api/v1/services

Доступ: администратор, аналитик.

Параметры запроса (URL Query)

Имя	Тип данных	Обязательный	Описание	Пример значения
page	number	Нет	Номер страницы. Начинается с 1. Размер страницы – 250 записей. Если параметр не указан, то используется значение по умолчанию – 1.	1
id	string	Нет	Идентификатор сервиса. Если параметр указан несколько раз, то формируется список и применяется логический оператор ИЛИ.	00000000-0000-0000-0000-000000000000
tenantID	string	Нет	Идентификатор тенанта сервиса. Если параметр указан несколько раз, то формируется список и применяется логический оператор ИЛИ. Если пользователь не имеет необходимой роли в указанном тенанте, то данный тенант игнорируется.	00000000-0000-0000-0000-000000000000
name	string	Нет	Имя сервиса. Регистронезависимое регулярное выражение (PCRE).	service ^My service$
kind	string	Нет	Тип сервиса. Если параметр указан несколько раз, то формируется список и применяется логический оператор ИЛИ.	collector, correlator, storage, agent
fqdn	string	Нет	FQDN сервиса. Регистронезависимое регулярное выражение (PCRE).	hostname ^hostname.example.com$
paired	bool	Нет	Выводить только те сервисы, которые выполнили первый запуск. Если параметр присутствует в URL query, его значение принимается за true. Указанные пользователем значения игнорируются. Пример: /api/v1/services?paired

Ответ

HTTP-код: 200

Формат: 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"`

}

Возможные ошибки

HTTP-код	Описание	Значение поля message	Значение поля details
400	Неверное значение параметра page	invalid query parameter value	page
400	Неверное значение параметр kind	invalid kind	<kind>
500	Любые другие внутренние ошибки	вариативное	вариативное

В начало

Поиск тенантов

GET /api/v1/tenants

Выводятся только доступные пользователю тенанты.

Доступ: администратор, аналитик.

Параметры запроса (URL Query)

Имя	Тип данных	Обязательный	Описание	Пример значения
page	number	Нет	Номер страницы. Начинается с 1. Размер страницы – 250 записей. Если параметр не указан, то используется значение по умолчанию – 1.	1
id	string	Нет	Идентификатор тенанта. Если параметр указан несколько раз, то формируется список и применяется логический оператор ИЛИ.	00000000-0000-0000-0000-000000000000
name	string	Нет	Название тенанта. Регистронезависимое регулярное выражение (PCRE).	tenant ^My tenant$
main	bool	Нет	Вывести только основной тенант. Если параметр присутствует в URL query, его значение принимается за true. Указанные пользователем значения игнорируются. Пример: /api/v1/tenants?main

Ответ

HTTP-код: 200

Формат: JSON

type Response []Tenant

type Tenant struct {

ID string `json:"id"`

Name string `json:"name"`

Main bool `json:"main"`

Description string `json:"description"`

EPS uint64 `json:"eps"`

EPSLimit uint64 `json:"epsLimit"`

Created string `json:"created"`

Updated string `json:"updated"`

}

Возможные ошибки

HTTP-код	Описание	Значение поля message	Значение поля details
400	Неверное значение параметра page	invalid query parameter value	page
500	Любые другие внутренние ошибки	вариативное	вариативное

В начало

Просмотр информации о предъявителе токена

GET /api/v1/users/whoami

Ответ

HTTP-код: 200

Формат: JSON

type Response struct {

ID string `json:"id"`

Name string `json:"name"`

Login string `json:"login"`

Email string `json:"email"`

Tenants []TenantAccess `json:"tenants"`

}

type TenantAccess struct {

ID string `json:"id"`

Name string `json:"name"`

Role string `json:"role"`

}

В начало

Обновление словаря в сервисах

POST /api/v1/dictionaries/update

Обновить можно только словари в ресурсах словарей типа таблица.

Доступ: администратор, аналитик.

Параметры запроса (URL Query)

Имя	Тип данных	Обязательный	Описание	Пример значения
collectorID	string	Нет	ID коллекторов, на которых будет обновлен словарь. Возможно указать несколько значений, тогда словарь будет обновлен на каждом из сервисов.	00000000-0000-0000-0000-000000000000
correlatorID	string	Нет	ID корреляторов, на которых будет обновлен словарь. Возможно указать несколько значений, тогда словарь будет обновле на каждом из сервисов.	00000000-0000-0000-0000-000000000000
dictionaryID	string	Да	ID словаря, который будет обновлен.	00000000-0000-0000-0000-000000000000

Если обновление на одном из сервисов заканчивается ошибкой, это не прерывает обновления на других сервисах.

Тело запроса

Имя поля multipart

Тип данных

Обязательный

Описание

Пример значения

file

CSV-файл

Да

Запрос содержит CSV-файл. Данные существующего словаря заменяются на данные этого файла. Первая строка CSV-файла с названиями столбцов не должна меняться.

key columns,column1,column2

key1,k1col1,k1col2

key2,k2col1,k2col2

Ответ

HTTP-код: 200

Формат: JSON

type Response struct {

ServicesFailedToUpdate []UpdateError `json:"servicesFailedToUpdate"`

}

type UpdateError struct {

ID string `json:"id"`

Err error `json:"err"`

}

Возвращает только ошибки для сервисов, на которых словари не были обновлены.

Возможные ошибки

HTTP-код	Описание	Значение поля message	Значение поля details
400	Неверное тело запроса	request body decode failed	возникшая ошибка
400	Нулевое количество строк словаря	request body required
400	Не указан ID словаря	invalid value	dictionaryID
400	Некорректное значение строки словаря	invalid value	rows или rows[i]
400	Словарь с указанным ID имеет неверный вид (не таблица)	can only update table dictionary
400	Попытка изменить столбцы словаря	columns must not change with update
403	Нет доступа к запрашиваемому ресурсу	access denied
404	Сервис не найден	service not found
404	Словарь не найден	dictionary not found	идентификатор сервиса
500	Любые другие внутренние ошибки	вариативное	вариативное

В начало

Получение словаря

GET /api/v1/dictionaries

Получить можно только словари в ресурсах словарей типа таблица.

Доступ: администратор, аналитик.

Параметры запроса (URL Query)

Имя	Тип данных	Обязательный	Описание	Пример значения
dictionaryID	string	Да	ID словаря, который будет получен	00000000-0000-0000-0000-000000000000

Ответ

HTTP-код: 200

Формат: text/plain; charset=utf-8

Возвращается CSV-файл с данными словаря в теле ответа.

В начало