Cервис управления информационной безопасностью
Cервис управления информационной безопасностью
Вход Регистрация

API

Документация API
Куда я попал?
SECURITM это SGRC система, ? автоматизирующая процессы в службах информационной безопасности. SECURITM помогает построить и управлять ИСПДн, КИИ, ГИС, СМИБ/СУИБ, банковскими системами защиты.
А еще SECURITM это место для обмена опытом и наработками для служб безопасности.
Подробнее
Наш канал
Для автоматического взаимодействия с SECURITM и других приложений, скриптов и коннекторов (например, Apache NiFi), используется JSON REST API.

Аутентификация

Для подключения к SECURITM по API используется API-токен.
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):
'Authorization' = "Bearer [TOKEN]"

В целях безопасности рекомендуется периодически менять токен.

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

POST запрос для импорта активов
https://service.securitm.ru/api/v1/assets/import

Для проведения импорта активов в SECURITM по API нужно
  1. Создать API токен
    Токен указывается в заголовке запроса
  2. Создать или выбрать шаблон импорта
    Название или UUID шаблона нужно добавить в тело запроса в параметр template
    Шаблоны импорта позволяют провести парсинг и логическую обработку любых данных, связав их с активами в SECURITM. Указание названия или UUID шаблона импорта обязательно в API запросе.
  3. Сформировать набор данных и поместить его в раздел assets API запроса
Примеры скриптов для проведения импорта активов в 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 нужно

  1. Создать API токен
    Токен указывается в заголовке запроса
  2. Указать тип активов, которые будут экспортироваться
  3. Если требуется - настроить фильтр полей активов
Пример скрипта на 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.
Пример:
http://nginx/api/v1/assets/get/os-29
2. В запросе отключить проверку сертификата 
Пример для 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-файлов и соглашаетесь с Политикой обработки персональных данных.