API
Куда я попал?
Для автоматического взаимодействия с SECURITM и других приложений, скриптов и коннекторов (например, Apache NiFi), используется JSON REST API.
Аутентификация
Для подключения к SECURITM по API используется API-токен.
API токен создается в Профиле команды. Там же его можно удалить или изменить.
Для доступа к управлению API токеном нужно обладать ролью Администратор команды.
Есть 2 способа передачи токена:
1. Передача токена в GET запросе
API токен создается в Профиле команды. Там же его можно удалить или изменить.
Для доступа к управлению API токеном нужно обладать ролью Администратор команды.
Есть 2 способа передачи токена:
1. Передача токена в GET запросе
https://service.securitm.ru/api/v1/[API method]?token=[token uid]&[API method params]
Внимание: способ передача токена в GET запросе небезопасен и может привести к его разглашению, этот способ следует использовать только в защищенной среде.
2. В заголовке запроса (Token-Based Authentication, Bearer Authentication):
2. В заголовке запроса (Token-Based Authentication, Bearer Authentication):
'Authorization' = "Bearer [TOKEN]"
В целях безопасности рекомендуется периодически менять токен.
Импорт активов
POST запрос для импорта активов
https://service.securitm.ru/api/v1/assets/import
Для проведения импорта активов в SECURITM по API нужно
- Создать API токен
Токен указывается в заголовке запроса - Создать или выбрать шаблон импорта
Название или UUID шаблона нужно добавить в тело запроса в параметр template
Шаблоны импорта позволяют провести парсинг и логическую обработку любых данных, связав их с активами в SECURITM. Указание названия или UUID шаблона импорта обязательно в API запросе. - Сформировать набор данных и поместить его в раздел assets API запроса
Примеры скриптов для проведения импорта активов в SECURITM:
Скрипт на PowerShell, проводящий импорт активов любых типов. Используется Шаблон SECURITM
Скрипт на PowerShell, проводящий импорт активов любых типов. Используется Шаблон SECURITM
# Укажите API Token для подключения (создается в профиле команды)
$token = '[TOKEN]'
# Укажите Шаблон, который будет использоваться для парсинга данных
$template = 'Шаблон SECURITM'
# Если у вас подписка Professional - укажите адрес вашего сервера SECURITM
$url = 'https://service.securitm.ru/api/v1/assets/import'
$headers = @{
'Authorization' = "Bearer $token"
}
$requestBody = [PSCustomObject]@{
'template' = $template
'assets' = @(
[ordered]@{
'Тип' = 'Работник'
'Название' = 'Иванов Иван Иванович'
'Описание' = 'Тестовый пользователь для импорта по API'
'Приоритет' = 'Низкий'
'Расположение' = 'Центральный офис'
'Подразделение' = 'Отдел информационной безопасности'
'Должность' = 'Специалист'
'Mail' = 'test@securitm.ru'
},
[ordered]@{
'Тип' = 'Операционная система'
'Название' = 'myserver.domain.local - 192.168.1.1'
'Описание' = 'Тестовый сервер для импорта по API'
'Приоритет' = 'Низкий'
'Расположение' = 'Центральный офис'
'Администратор' = 'Иванов Иван Иванович'
'IP адрес' = '192.168.1.1'
'Hostname' = 'myserver'
'Домен' = 'domain.local'
}
) } | ConvertTo-Json -Depth 3
try {
$response = Invoke-RestMethod -Method Post -Uri $url -ContentType "application/json; charset=utf-8" -Headers $headers -Body $requestBody
Write-Host ($response | ConvertTo-Json -Depth 10)
} catch {
Write-Host 'Status code:' $_.Exception.Response.StatusCode.Value__
$result = $_.Exception.Response.GetResponseStream()
$reader = New-Object System.IO.StreamReader($result)
$reader.BaseStream.Position = 0
$reader.DiscardBufferedData()
$responseBody = $reader.ReadToEnd()
Write-Host $responseBody
} finally {
if ($result) {
$result.Close()
}
if ($reader) {
$reader.Close()
}
}
Скрипт на Python, проводящий импорт активов любых типов. Используется Шаблон SECURITM
Скрипт на PowerShell для сбора активов (пользователей, компьютеров, групп, состава групп) из локального Active Directory и импорта по API в SECURITM.
Перед импортом нужно добавить в команду следующие типы активов: Работник, Группа LDAP, Windows Server (включая подтипы для конкретных версий ОС)
Используются шаблоны импорта
- Active Directory Users
- Active Directory Computers
- Active Directory Groups
- Active Directory Group members
Скрипт на PowerShell который обрабатывает CSV файл выгруженный из Центра управления DrWeb, нормализует его и загружает в SECURITM по API с использованием Community шаблона DrWeb CSV + API
# Скрипт для импорта в SECURITM хостов и статуса антивирусной защиты из DrWeb
# Из DrWeb экспортируются данные по хостам в CSV файл
# На сервере SECURITM используется Community шаблон "DrWeb CSV + API"
# Укажите API Token для подключения (создается в профиле команды)
$globalToken = '[TOKEN]'
# Укажите Шаблон, который будет использоваться для парсинга данных
$globalTemplate = 'DrWeb CSV + API'
# Если у вас подписка Professional - укажите адрес вашего сервера SECURITM
$globalUrl = 'https://service.securitm.ru/api/v1/assets/import'
# Укажите путь до CSV файла с выгрузкой данных из DrWeb
# Формат файла:
# Station;Groups;Address;MAC address
# mysrv.mydomain.local;Linux;ssl://192.168.1.1:41334;00:0c:29:f1:f5:c7
$csvFile = "c: mpdrweb.csv"
# Функция парсинга файла DrWeb
function Get-DrWebDataFromCSV {
$objects = @()
$data = Import-Csv -Path $csvFile -Delimiter ";"
foreach ($row in $data) {
# Создаем объект с данными из каждой строки
$object = [PSCustomObject]@{
hostname = $row.Station -replace "..*"
domain = if(($row.Station).Contains('.')) {($row.Station).Substring(($row.Station).IndexOf(".")+1)} Else {''}
assettype = $row.Groups
ip = $row.Address -replace ".*ssl://" -replace ":.*"
mac = $row.'MAC address'
is_av_installed = 1;
note = 'Импорт из DrWeb CSV'
name = "$($row.Station) - $($row.Address -replace '.*ssl://' -replace ':.*')"
}
# Добавляем объект в массив
$objects += $object
}
return $objects;
}
# Функция импорта данных в SECURITM
function Send-ObjectsToApi {
param (
[Parameter(Mandatory = $true)]
[array]$objects,
[Parameter(Mandatory = $true)]
[string]$template
)
Write-Host "Отправляем API запросы в SECURITM по шаблону $($template)"
# Определение заголовков запроса
$headers = @{
'Authorization' = "Bearer $globalToken"
}
# Инициализация индекса и размера секции объектов
$idx = 0
$size = 100
# Цикл по объектам в массиве
while ($($size * $idx) -lt $objects.Length){
Write-Host "$($idx*$size) - $(($idx+1)*$size) объектов"
# Получение секции объектов заданного размера
$section = $objects | Select-Object -First $size -Skip ($size * $idx)
$idx ++
# Создание тела запроса в формате JSON
$requestBody = [PSCustomObject]@{
'template' = $template
'assets' = @($section)
} | ConvertTo-Json -Depth 3
try {
# Если включена HTTPS инспекция
[Net.ServicePointManager]::ServerCertificateValidationCallback = { $true }
[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
# Отправка POST-запроса на URL с заданными параметрами
$response = Invoke-RestMethod -Method Post -Uri $globalUrl -ContentType "application/json; charset=utf-8" -Headers $headers -Body $requestBody
Write-Host ($response | ConvertTo-Json -Depth 10)
} catch {
if($_.Exception) {
Write-Host 'Status code:' $_.Exception.Response.StatusCode.Value__
$result = $_.Exception.Response.GetResponseStream()
$reader = New-Object System.IO.StreamReader($result)
$reader.BaseStream.Position = 0
$reader.DiscardBufferedData()
$responseBody = $reader.ReadToEnd()
} else {
Write-Host 'Unexpected error, may be timeout'
}
Write-Host $responseBody
} finally {
if ($result) {
$result.Close()
}
if ($reader) {
$reader.Close()
}
}
}
}
$objects = Get-DrWebDataFromCSV -file $csvFile
Send-ObjectsToApi -objects $objects -template $globalTemplate
Рекомендация: Если вы планируете регулярный запуск скриптов через планировщик заданий, удобно можно использовать такой запускающий Batch скрипт, который будет инициировать запуск PowerShell скрипта и сохранять все результаты его работы в лог-файл. Скрипты должны находиться в одной папке и одинаково называться, например import.cmd и import.ps1
@echo off
set "log=%~dpn0.log"
chcp 1251 >nul
(echo Start @ %date% %time% & echo ----------) > "%log%"
powershell.exe -ExecutionPolicy Bypass -File "%~dpn0.ps1" >> "%log%" 2>&1
(echo ---------- & echo Finish @ %date% %time%) >> "%log%"
chcp 866 >nul
Экспорт активов
GET запрос для экспорта активов
https://service.securitm.ru/api/v1/assets/get/[asset type]?[asset fields]
где
- [asset type] - обозначение типа актива, который будет экспортироваться.
Узнать обозначение типа актива можно в URL браузера зайдя в соответствующий реестр.
Пример: os-18, linux-server-8 - [asset fields] - поля активов, которые будут выгружены
Указывать не обязательно, по умолчанию будут выгружены все поля.
Пример: ip&version
Для проведения экспорта активов из SECURITM по API нужно
- Создать API токен
Токен указывается в заголовке запроса - Указать тип активов, которые будут экспортироваться
- Если требуется - настроить фильтр полей активов
Пример скрипта на PowerShell для экспорта активов
# Укажите API Token для подключения (создается в профиле команды)
$token = '[TOKEN]'
# Если у вас подписка Professional - укажите адрес вашего сервера SECURITM
# Укажите тип актива который собираетесь экспортировать из SECURITM.
# После "?" укажите поля, которые подлежат экспорту. Если не указывать - будут выгружены все поля.
$url = 'https://service.securitm.ru/api/v1/assets/get/os-18?ip'
$headers = @{
'Authorization' = "Bearer $token"
}
try {
$response = Invoke-RestMethod -Method Get -Uri $url -ContentType "application/json; charset=utf-8" -Headers $headers
Write-Host ($response | ConvertTo-Json -Depth 10)
} catch {
Write-Host 'Status code:' $_.Exception.Response.StatusCode.Value__
$result = $_.Exception.Response.GetResponseStream()
$reader = New-Object System.IO.StreamReader($result)
$reader.BaseStream.Position = 0
$reader.DiscardBufferedData()
$responseBody = $reader.ReadToEnd()
Write-Host $responseBody
} finally {
if ($result) {
$result.Close()
}
if ($reader) {
$reader.Close()
}
}
Обращение сам к себе
Существует возможность обращаться к SECURITM по API непосредственно из SECURITM. Через запуск скриптов в модуле RPA.
Функция активирована в локальных (on-premise) инсталляциях.
Чтобы из скрипта в RPA можно было сделать запрос к самому себе нужно:
1. В качестве адреса сервера указать "nginx", доступ по протоколу HTTP.
Пример:
Функция активирована в локальных (on-premise) инсталляциях.
Чтобы из скрипта в RPA можно было сделать запрос к самому себе нужно:
1. В качестве адреса сервера указать "nginx", доступ по протоколу HTTP.
Пример:
http://nginx/api/v1/assets/get/os-29
2. В запросе отключить проверку сертификата
Пример для PowerShell:
Пример для PowerShell:
$globalUrl = 'http://nginx/api/v1/assets/get/os-18?ip'
$globalToken = '[TOKEN]'
$headers = @{
'Authorization' = "Bearer $token"
}
$response = Invoke-RestMethod -SkipCertificateCheck -Method Get -Uri globalUrl -Headers $headers -ContentType "application/json; charset=utf-8"
Пример скрипта на PowerShell который забирает все хосты (активы типа Операционная система) и нормализует их названия
// в проработке
Мы используем cookie-файлы, чтобы получить статистику, которая помогает нам улучшить сервис для вас с целью персонализации сервисов и предложений. Вы может прочитать подробнее о cookie-файлах или изменить настройки браузера. Продолжая пользоваться сайтом, вы даёте согласие на использование ваших cookie-файлов и соглашаетесь с Политикой обработки персональных данных.