Содержание
- Операции REST API v2
- Просмотр списка активных листов на корреляторе
- Импорт записей в активный лист
- Поиск алертов
- Закрытие алертов
- Поиск активов
- Импорт активов
- Удаление активов
- Поиск событий
- Просмотр информации о кластере
- Поиск ресурсов
- Загрузка файла с ресурсами
- Просмотр содержимого файла с ресурсами
- Импорт ресурсов
- Экспорт ресурсов
- Скачивание файла с ресурсами
- Поиск сервисов
- Поиск тенантов
- Просмотр информации о предъявителе токена
- Обновление словаря в сервисах
- Получение словаря
- Просмотр пользовательских полей активов
- Создание резервной копии Ядра KUMA
- Восстановление Ядра KUMA из резервной копии
- Просмотр списка контекстных таблиц в корреляторе
- Импорт записей в контекстную таблицу
- Экспорт записей из контекстной таблицы
Просмотр списка активных листов на корреляторе
GET /api/v2/activeLists
Целевой коррелятор должен быть запущен.
Доступ: Главный администратор, Администратор тенанта, Аналитик второго уровня, Аналитик первого уровня.
Параметры запроса
Имя |
Тип данных |
Обязательный |
Описание |
Пример значения |
correlatorID |
string |
Да |
Идентификатор сервиса коррелятора |
00000000-0000-0000-0000-000000000000 |
Ответ
HTTP-код: 200
Формат: JSON
|
Возможные ошибки
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/v2/activeLists/import
Целевой коррелятор должен быть запущен.
Доступ: Главный администратор, Администратор тенанта, Аналитик второго уровня, Аналитик первого уровня (может импортировать данные в любой лист коррелятора доступного тенанта, даже если активный лист создан в Общем тенанте).
Параметры запроса (URL Query)
Имя |
Тип данных |
Обязательный |
Описание |
Пример значения |
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/v2/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 |
вариативное |
400 |
Ошибка парсинга тела запроса |
correlator API request failed |
вариативное |
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/v2/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 |
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
|
Возможные ошибки
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/v2/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/v2/assets
Информация о программном обеспечении активов из KSC не хранится в KUMA и не будет показана в ответе.
Доступ: Главный администратор, Администратор тенанта, Аналитик второго уровня, Аналитик первого уровня, Младший аналитик, Доступ к объектам НКЦКИ, Доступ к объектам КИИ.
Роль Доступ к общим ресурсам выдается только для Общего тенанта: в этом тенанте не может быть активов, но категории в тенанте есть. Для этой роли в ответ ничего не вернется.
Параметры запроса
Имя |
Тип данных |
Обязательный |
Описание |
Пример значения |
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). |
example.com |
ip |
string |
Нет |
IP-адрес актива. Регистронезависимое регулярное выражение (PCRE). |
10.10 ^192.168.1.2$ |
mac |
string |
Нет |
MAC-адрес актива. Регистронезависимое регулярное выражение (PCRE). |
^00:0a:95:9d:68:16$ |
Ответ
HTTP-код: 200
Формат: JSON
|
Возможные ошибки
HTTP-код |
Описание |
Значение поля message |
Значение поля details |
400 |
Неверное значение параметра page |
invalid query parameter value |
page |
500 |
Любые другие внутренние ошибки |
вариативное |
вариативное |
Импорт активов
Особенности идентификации, создания и обновления активов
Активы импортируются в соответствии с правилами слияния данных об активах.
POST /api/v2/assets/import
Массовое создание или обновление активов.
Если указан FQDN актива, он играет роль уникального идентификатора актива в рамках тенанта. Если указано более одного FQDN, используется первый адрес из указанного массива адресов. Если FQDN не указан, для идентификации актива используется первый IP-адрес из указанного массива адресов. Если имя актива не указано, оно заполняется либо значением FQDN, либо значением первого IP-адреса. Активы, импортированные из KSC не могут быть обновлены, поэтому в процессе импорта могут возникать конфликты по FQDN, если в тенанте уже существует KSC-актив с таким FQDN. Возникновение такого конфликта препятствует обработке конфликтующего актива, но не препятствует обработке других активов, указанных в теле запроса. Позволяет заполнять пользовательские поля по uuid из настроек assetsCustomFields.
Доступ: Главный администратор, Администратор тенанта, Аналитик второго уровня, Аналитик первого уровня.
Тело запроса
Формат: JSON
|
Обязательные поля 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
|
Возможные ошибки
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 адрес |
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/v2/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
|
Возможные ошибки
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/v2/events
Разрешены только поисковые или агрегационные запросы (SELECT).
Доступ: Главный администратор, Администратор тенанта, Аналитик второго уровня, Аналитик первого уровня, Младший аналитик, Доступ к объектам НКЦКИ, Доступ к объектам КИИ.
Тело запроса
Формат: 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/v2/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 |
Ответ
HTTP-код: 200
Формат: JSON
|
Возможные ошибки
HTTP-код |
Описание |
Значение поля message |
Значение поля details |
---|---|---|---|
400 |
Неверное значение параметра page |
invalid query parameter value |
page |
500 |
Любые другие внутренние ошибки |
вариативное |
вариативное |
Поиск ресурсов
GET /api/v2/resources
Доступ: Главный администратор, Администратор тенанта, Аналитик второго уровня, Аналитик первого уровня, Доступ к общим ресурсам.
Ресурсы типа storage доступны только Главному администратору и Администратору тенанта.
Параметры запроса (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 |
kind |
string |
Нет |
Тип ресурса. Если параметр указан несколько раз, то формируется список и применяется логический оператор ИЛИ |
collector, correlator, storage, activeList, aggregationRule, connector, correlationRule, dictionary, enrichmentRule, destination, filter, normalizer, responseRule, search, agent, proxy, secret, segmentationRule, emailTemplate, contextTable, eventRouter |
Ответ
HTTP-код: 200
Формат: JSON
|
Возможные ошибки
HTTP-код |
Описание |
Значение поля message |
Значение поля details |
400 |
Неверное значение параметра page |
invalid query parameter value |
page |
400 |
Неверное значение параметр kind |
invalid kind |
<kind> |
500 |
Любые другие внутренние ошибки |
вариативное |
вариативное |
Загрузка файла с ресурсами
POST /api/v2/resources/upload
Доступ: Главный администратор, Администратор тенанта, Аналитик второго уровня, Аналитик первого уровня.
Тело запроса
Зашифрованное содержимое файла с ресурсами в бинарном формате.
Ответ
HTTP-код: 200
Формат: JSON
Идентификатор файла. Следует указать его в теле запросов на просмотр содержимого файла и на импорт ресурсов.
|
Возможные ошибки
HTTP-код |
Описание |
Значение поля message |
Значение поля details |
400 |
Размер файла превышает максимально допустимый (64 МБ) |
maximum file size is 64 MB |
- |
403 |
Пользователь не имеет необходимых ролей ни в одном из тенантов |
access denied |
- |
500 |
Любые другие внутренние ошибки |
вариативное |
вариативное |
Просмотр содержимого файла с ресурсами
POST /api/v2/resources/toc
Доступ: Главный администратор, Администратор тенанта, Аналитик второго уровня, Аналитик первого уровня.
Тело запроса
Формат: JSON
Имя |
Тип данных |
Обязательный |
Описание |
Пример значения |
fileID |
string |
Да |
Идентификатор файла, полученный в результате выполнения загрузки файла с ресурсами. |
00000000-0000-0000-0000-000000000000 |
password |
string |
Да |
Пароль файла с ресурсами. |
SomePassword!88 |
Ответ
HTTP-код: 200
Формат: JSON
Версия файла, список ресурсов, категорий, папок.
Идентификатор полученных ресурсов необходимо использовать при импорте.
|
Импорт ресурсов
POST /api/v2/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 – заменить (используется при разрешении конфликтов)
|
Ответ
HTTP-код |
Тело |
|
204 |
|
|
409 |
Идентификаторы импортируемых ресурсов, конфликтующих с уже существующими по ID. В этом случае необходимо повторить операцию импорта, указав для данных ресурсов следующие действия: 0 – не импортировать 2 – заменить
|
Экспорт ресурсов
POST /api/v2/resources/export
Доступ: Главный администратор, Администратор тенанта, Аналитик второго уровня, Аналитик первого уровня, Доступ к общим ресурсам.
Тело запроса
Формат: JSON
Имя |
Тип данных |
Обязательный |
Описание |
Пример значения |
ids |
[]string |
Да |
Идентификаторы ресурсов, которые необходимо экспортировать |
["00000000-0000-0000-0000-000000000000"] |
password |
string |
Да |
Пароль файла с экспортированными ресурсами |
SomePassword!88 |
tenantID |
string |
Да |
Идентификатор тенанта, которому принадлежат экспортируемые ресурсы |
00000000-0000-0000-0000-000000000000 |
Ответ
HTTP-код: 200
Формат: JSON
Идентификатор файла с экспортированными ресурсами. Следует использовать его в запросе на скачивание файла с ресурсами.
|
Скачивание файла с ресурсами
GET /api/v2/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/v2/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 |
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
|
Возможные ошибки
HTTP-код |
Описание |
Значение поля message |
Значение поля details |
400 |
Неверное значение параметра page |
invalid query parameter value |
page |
400 |
Неверное значение параметр kind |
invalid kind |
<kind> |
500 |
Любые другие внутренние ошибки |
вариативное |
вариативное |
Поиск тенантов
GET /api/v2/tenants
Выводятся только доступные пользователю тенанты.
Доступ: Главный администратор, Администратор, Аналитик второго уровня, Аналитик первого уровня, Младший аналитик, Работа с НКЦКИ, Доступ к КИИ, Доступ к общим ресурсам.
Параметры запроса (URL Query)
Имя |
Тип данных |
Обязательный |
Описание |
Пример значения |
page |
number |
Нет |
Номер страницы. Начинается с 1. Размер страницы – 250 записей. Если параметр не указан, то используется значение по умолчанию – 1. |
1 |
id |
string |
Нет |
Идентификатор тенанта. Если параметр указан несколько раз, то формируется список и применяется логический оператор ИЛИ. |
00000000-0000-0000-0000-000000000000 |
name |
string |
Нет |
Название тенанта. Регистронезависимое регулярное выражение (PCRE). |
tenant |
main |
bool |
Нет |
Вывести только основной тенант. Если параметр присутствует в URL query, его значение принимается за true. Указанные пользователем значения игнорируются. Пример: /api/v1/tenants?main |
|
Ответ
HTTP-код: 200
Формат: JSON
|
Возможные ошибки
HTTP-код |
Описание |
Значение поля message |
Значение поля details |
400 |
Неверное значение параметра page |
invalid query parameter value |
page |
500 |
Любые другие внутренние ошибки |
вариативное |
вариативное |
Просмотр информации о предъявителе токена
GET /api/v2/users/whoami
Ответ
HTTP-код: 200
Формат: JSON
|
Обновление словаря в сервисах
POST /api/v2/dictionaries/update
Обновить можно только словари в ресурсах словарей типа таблица.
Доступ: Главный администратор, Администратор тенанта, Аналитик второго уровня, Аналитик первого уровня.
Параметры запроса (URL Query)
Имя |
Тип данных |
Обязательный |
Описание |
Пример значения |
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/v2/dictionaries
Получить можно только словари в ресурсах словарей типа таблица.
Доступ: Главный администратор, Администратор тенанта, Аналитик второго уровня, Аналитик первого уровня.
Параметры запроса (URL Query)
Имя |
Тип данных |
Обязательный |
Описание |
Пример значения |
dictionaryID |
string |
Да |
ID словаря, который будет получен |
00000000-0000-0000-0000-000000000000 |
Ответ
HTTP-код: 200
Формат: text/plain; charset=utf-8
Возвращается CSV-файл с данными словаря в теле ответа.
В началоПросмотр пользовательских полей активов
GET /api/v2/settings/id/:id
Пользователь может просматривать список пользовательских полей, сделанных пользователем KUMA в веб-интерфейсе программы.
Пользовательское поле представляет из себя контейнер для ввода текста. При необходимости может использоваться значение по умолчанию и маска для проверки корректности вводимого текста в формате https://pkg.go.dev/regexp/syntax. Все символы косой черты в маске необходимо дополнительно экранировать.
Доступ: Главный администратор, Администратор тенанта Main.
Параметры запроса
Имя |
Тип данных |
Обязательный |
Описание |
Пример значения |
id |
string |
Да |
Идентификатор конфигурации пользовательских полей |
00000000-0000-0000-0000-000000000000 |
Ответ
HTTP-код: 200
Формат: JSON
|
Возможные ошибки
HTTP-код |
Описание |
Значение поля message |
Значение поля details |
404 |
Параметры не найдены: неверный идентификатор или параметров нет |
Not found in database |
null |
500 |
Любые другие внутренние ошибки |
вариативное |
вариативное |
Создание резервной копии Ядра KUMA
GET /api/v2/system/backup
Доступ: Главный администратор.
Запрос не имеет параметров.
В ответ на запрос возвращается архив tar.gz, содержащий резервную копию Ядра KUMA. На хосте, где установлено Ядро, резервная копия не сохраняется. Сертификаты включаются в состав резервной копии.
Если операция выполнена успешно, создается событие аудита со следующими параметрами:
DeviceAction = "Core backup created"
SourceUserID = "<user-login>"
Восстановить Ядра KUMA из резервной копии можно с помощью API-запроса POST /api/v2/system/restore
.
Восстановление Ядра KUMA из резервной копии
POST /api/v2/system/restore
Доступ: Главный администратор.
Запрос не имеет параметров.
Тело запроса должно содержать архив с резервной копией Ядра KUMA, полученный в результате выполнения API-запроса GET /api/v2/system/backup
.
После получения архива с резервной копией KUMA выполняет следующие действия:
- Распаковывает архив с резервной копией Ядра KUMA во временную директорию.
- Сравнивает версию текущей KUMA и с версией резервной копии KUMA. Восстановление данных из резервной копии доступно только при сохранении версии KUMA.
Если версии соответствуют друг другу, создается событие аудита со следующими параметрами:
DeviceAction = "Core restore scheduled"
SourceUserID = "<имя пользователя инициировавшего восстановление KUMA из резервной копии"
- Если версии не различаются, выполняет восстановление данных из резервной копии Ядра KUMA.
- Удаляет временную директорию и стартует в штатном режиме.
В журнале Ядра KUMA появится запись "WARN: restored from backup".
Просмотр списка контекстных таблиц в корреляторе
GET /api/v2/contextTables
Целевой коррелятор должен быть запущен.
Доступ: Главный администратор, Администратор тенанта, Аналитик второго уровня, Аналитик первого уровня.
Параметры запроса (URL Query)
Имя |
Тип данных |
Обязательный |
Описание |
Пример значения |
correlatorID |
string |
Да |
Идентификатор сервиса коррелятора |
00000000-0000-0000-0000-000000000000 |
Ответ
HTTP-код: 200
Формат: 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"`
}
Возможные ошибки
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/v2/contextTables/import
Целевой коррелятор должен быть запущен.
Доступ: Главный администратор, Администратор тенанта, Аналитик второго уровня, Аналитик первого уровня (может импортировать данные в любую таблицу коррелятора доступного тенанта, даже если контекстная таблица, создана в Общем тенанте).
Параметры запроса (URL Query)
Имя |
Тип данных |
Обязательный |
Описание |
Пример значения |
correlatorID |
string |
Да |
Идентификатор сервиса коррелятора |
00000000-0000-0000-0000-000000000000 |
contextTableID |
string |
Если не указан contextTableName |
Идентификатор контекстной таблицы |
00000000-0000-0000-0000-000000000000 |
contextTableName |
string |
Если не указан contextTableID |
Имя контекстной таблицы |
Attackers |
format |
string |
Да |
Формат импортируемых записей |
CSV, TSV, internal |
clear |
bool |
Нет |
Очистить контекстную таблицу перед выполнением импорта. Если параметр присутствует в URL query, его значение принимается как true. Указанные пользователем значения игнорируются. |
/api/v2/contextTables/import?clear |
Тело запроса
Формат |
Содержимое |
CSV |
Первая строка - заголовок, где перечислены поля, разделенные запятой. Остальные строки - значения, соответствующие полям в заголовке, разделенные запятой. Количество полей на каждой строке должно быть одинаковым и должно соответствовать количеству полей в схеме контекстной таблицы. Значения списочных полей разделяются символом "|". Например, значение списочного поля целочисленного типа - 1|2|3. |
TSV |
Первая строка - заголовок, где перечислены поля, разделенные TAB. Остальные строки - значения, соответствующие полям в заголовке, разделенные TAB. Количество полей на каждой строке должно быть одинаковым и должно соответствовать количеству полей в схеме контекстной таблицы. Значения списочных полей разделяются символом "|". |
internal |
Каждая строка содержит один индивидуальный объект JSON. Данные в internal формате можно получить путем экспорта содержимого контекстной таблицы из коррелятора в веб-консоли KUMA. |
Ответ
HTTP-код: 204
Возможные ошибки
HTTP-код |
Описание |
Значение поля message |
Значение поля details |
---|---|---|---|
400 |
Не указан идентификатор сервиса коррелятора. |
query parameter required |
correlatorID |
400 |
Не указан ни параметр contextTableID, ни параметр contextTableName. |
one of query parameters required |
contextTableID, contextTableName |
400 |
Не указан параметр format. |
query parameter required |
format |
400 |
Параметр format имеет неверное значение. |
invalid query parameter value |
format |
400 |
Тело запроса имеет нулевую длину. |
request body required |
- |
400 |
Ошибка парсинга тела запроса, а том числе соответствие схеме контекстной таблицы наименования полей и типов импортируемой записи. |
correlator API request failed |
вариативное |
403 |
Пользователь не имеет необходимой роли в тенанте коррелятора. |
access denied |
- |
404 |
Сервис с указанным идентификатором correlatorID не найден. |
service not found |
- |
404 |
Контекстная таблица не найдена. |
context table not found |
- |
406 |
Сервис с указанным идентификатором correlatorID не является коррелятором. |
service is not correlator |
- |
406 |
Коррелятор не выполнил первый запуск. |
service not paired |
- |
406 |
Тенант коррелятора отключен. |
tenant disabled |
- |
406 |
Поиск контекстной таблицы выполнялся по имени contextTableName и было найдено более одной контекстной таблицы. |
more than one matching context tables found |
- |
50x |
Не удалось обратиться к API коррелятора. |
correlator API request failed |
вариативное |
500 |
Ошибка подготовки данных для импорта в сервис коррелятора. |
context table process import request failed |
вариативное |
500 |
Любые другие внутренние ошибки. |
вариативное |
вариативное |
Экспорт записей из контекстной таблицы
GET /api/v2/contextTables/export
Целевой коррелятор должен быть запущен.
Доступ: Главный администратор, Администратор тенанта, Аналитик второго уровня, Аналитик первого уровня.
Параметры запроса (URL Query)
Имя |
Тип данных |
Обязательный |
Описание |
Пример значения |
correlatorID |
string |
Да |
Идентификатор сервиса коррелятора |
00000000-0000-0000-0000-000000000000 |
contextTableID |
string |
Если не указан contextTableName |
Идентификатор контекстной таблицы |
00000000-0000-0000-0000-000000000000 |
contextTableName |
string |
Если не указан contextTableID |
Имя контекстной таблицы |
Attackers |
Ответ
HTTP-код: 200
Формат: application/octet-stream
Тело: экспортированные данные контекстной таблицы в формате internal - каждая строка содержит один индивидуальный объект JSON.
Возможные ошибки
HTTP-код |
Описание |
Значение поля message |
Значение поля details |
---|---|---|---|
400 |
Не указан идентификатор сервиса коррелятора. |
query parameter required |
correlatorID |
400 |
Не указан ни параметр contextTableID, ни параметр contextTableName. |
one of query parameters required |
contextTableID, contextTableName |
403 |
Пользователь не имеет необходимой роли в тенанте коррелятора. |
access denied |
- |
404 |
Сервис с указанным идентификатором correlatorID не найден. |
service not found |
- |
404 |
Контекстная таблица не найдена. |
context table not found |
- |
406 |
Сервис с указанным идентификатором correlatorID не является коррелятором. |
service is not correlator |
- |
406 |
Коррелятор не выполнил первый запуск. |
service not paired |
- |
406 |
Тенант коррелятора отключен. |
tenant disabled |
- |
406 |
Поиск контекстной таблицы выполнялся по имени contextTableName и было найдено более одной контекстной таблицы. |
more than one matching context tables found |
- |
50x |
Не удалось обратиться к API коррелятора. |
correlator API request failed |
вариативное |
500 |
Любые другие внутренние ошибки. |
вариативное |
вариативное |