1. Зайдите в Профиль команды ➡️ Api токены
2. Доступные действия
   1. Создание токена (по кнопке Создать токен справа вверху)
   2. Копирование токена в буфер
   3. Редактирование токена
   4. Удаление токена
3. Для создания токена  необходимо заполнить поля:
   1. Название. 
   2. Описание.
   3. IP. Необязательное поле. При необходимости указать IP для ограничения предоставления данных по адресу. Пустое поле позволяет предоставлять данные по любым адресам.
   4. Права доступа. Для добавления прав необходимо выбрать:
      1. Модуль. Доступные значения Активы (модуль Активы) и Уязвимости (модуль Технические уязвимости). 
      2. Права. Доступные значения: просмотр, создание, обновление, удаление, импорт.
      3. нажать кнопку Добавить.
   5. При создании токена для импорта потребуется указать шаблон импорта в поле Шаблон  для импорта активов или Сканер для импорта уязвимостей.

Права доступа

• просмотр - получение активов;
• создание - создание активов;
• обновление - обновление активов;
• удаление - удаление активов;
• импорт - данная настройка в рамках модуля. Активы- это выбор шаблона импорта активов. Есть возможность выбора как отдельного шаблона, так и "Все шаблоны". 

• просмотр - получение уязвимостей;
• создание - создание уязвимостей;
• обновление - обновление уязвимостей;
• удаление - удаление уязвимостей;
• импорт - в рамках модуля Уязвимости - это выбор сканера от которого мы грузим файл. Есть возможность выбора как отдельного сканера, так и "Все сканеры".

• просмотр - получение списка задач;
• создание - создание новых задач;
• обновление - обновление задач;
• удаление - удаление задач.

Миграция прав предыдущих токенов

https://service.securitm.ru/api/v1/[API method]?token=[token uid]&[API method params]

'Authorization' = "Bearer [TOKEN]"

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

https://service.securitm.ru/api/v1/assets/import

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

# Укажите 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()
    }
}

pwsh.exe -ExecutionPolicy Bypass -File ad-objects.ps1
-server 'service.securitm.ru'
-token '***'
-adunits 'OU=Network_Repository,DC=domain,DC=local'
-departments

# Имя веб-сервера SECURITM
-server 'имя_сервера'

# API токен с правами просмотра, создания, обновления, импорта для модуля «Активы». Токен создается в Профиле команды – Api токены
-token '***'

# DN имена OU, из которых будет производиться импорт объектов. Например: 'OU=Groups,DC=domain,DC=local','OU=Users,DC=domain,DC=local','OU=Computers,DC=domain,DC=local'
-adunits 'OU1_DN',' OU2_DN',...

# Отделы и организации из свойств учетных записей Active Directory будут добавлены в реестр активов
-departments

# Также импортировать отключенных пользователей
-disabledusers

# Также импортировать отключенные компьютеры
-disabledcomputers

# Не импортировать группы
-skipgroups
# Не импортировать пользователей
-skipusers
# Не импортировать компьютеры
-skipcomputers

# Имя шаблона импорта для групп. По умолчанию «AD Groups»
-grouptemplate 'AD Groups'

# Имя типа актива для групп. По умолчанию «Группа LDAP»
-grouptype 'Группа LDAP'

# Имя шаблона импорта для импорта связей между группами и пользователями/компьютерами. По умолчанию «AD Group members»
-groupmemberstemplate 'AD Group members'

# Имя шаблона импорта для пользователей. По умолчанию «AD Users»
-usertemplate 'AD Users'

# Имя типа актива для пользователей. По умолчанию «Работник»
-usertype 'Работник'

# Имя шаблона импорта для компьютеров. По умолчанию «AD Computers»
-computertemplate 'AD Computers'

# Имя шаблона импорта для организаций. По умолчанию «AD Companies»
-companytemplate 'AD Companies'

# Имя типа актива для организаций. По умолчанию «Юридическая структура»
-companytype 'Юридическая структура'

# Имя шаблона импорта для отделов. По умолчанию «AD Departments»
-departmenttemplate 'AD Departments'

# Имя типа актива для отделов. По умолчанию «Подразделение»
-departmenttype 'Подразделение'

pwsh.exe -ExecutionPolicy Bypass -File ad-objects.ps1 -server 'cloud.securitm.ru' -token '***' -adunits 'OU=Network_Repository,DC=domain,DC=local' -departments -disabledusers -disabledcomputers

pwsh.exe -ExecutionPolicy Bypass -File ad-objects.ps1 -server 'cloud.securitm.ru' -token '***' -adunits 'OU=Dep1,DC=domain,DC=local','OU=Dep2,DC=domain,DC=local' -skipgroups

# Скрипт для импорта в 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

@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

Экспорт активов

https://service.securitm.ru/api/v1/assets/get/[asset type]?[asset fields]

• [asset type] - обозначение типа актива, который будет экспортироваться.
  Узнать обозначение типа актива можно в URL браузера зайдя в соответствующий реестр.
  Пример: os-18, linux-server-8
• [asset fields] - поля активов, которые будут выгружены
  Указывать не обязательно, по умолчанию будут выгружены все поля.
  Пример: ip&version

1. Создать API токен
   Токен указывается в заголовке запроса
2. Указать тип активов, которые будут экспортироваться
3. Если требуется - настроить фильтр полей активов

# Укажите 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()
    }
}

Обращение к самому себе

http://nginx/api/v1/assets/get/os-29

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

Методы

• GET - получение ресурса;
• POST - создание ресурса;
• PUT - обновление ресурса;
• DELETE - удаление ресурса.

GET

GET https://localhost/api/v2/tasks
Accept: application/json
Authorization: Bearer [TOKEN]

GET /?filters={fields: [{uuid: "task_uuid", op: "eq"}]}

• 'uuid' - идентификатор задачи;
• 'name' - название задачи;
• 'done_at' - дата завершения; 
• 'priority' - приоритет;
• 'created_at' - дата создания;
• 'responsible_uuid' - идентификатор актива, назначенного ответственным; 
• 'author_uuid' - идентификатор пользователя, являющегося автором задачи; 
• 'is_done' - флаг завершения задачи.

• 'eq' - равно;
• 'ne' - не равно;
• 'ge' - больше или равно;
• 'gt' - больше;
• 'le' - меньше или равно;
• 'lt' - меньше;
• 'in' - несколько значений;
• 'like' - вхождение;
• 'date-eq' - дата равно;
• 'date-gt' - дата больше;
• 'date-lt' - дата меньше.

1. Экспорт уязвимостей
2. Импорт уязвимостей (JSON)
3. Импорт файла сканера (FILE)

Экспорт уязвимостей

Content-Type: application/json
Authorization: Bearer your_token

• perPage: количество выводимых на странице объектов, по умолчанию = 10.
• page: номер страницы, по умолчанию = 1.
• sorting: сортировка вывода, принимает массив ["column" => "name", ''order" => "asc"]
• sorting.column: колонка сортировки, возможные значения name, ip_count, severity, integral, по умолчанию = "name".
• sorting.order: порядок сортировки, возможные значения asc, desc, по умолчанию = "asc".
• filters: фильтрация уязвимостей, возможные фильтры (name, ip), по умолчанию не используются.

• filterByName 
• filterByIp

"filters": {  
    "filterByIp": {    
        "enable": true,    
        "value": ["192.168.3.41", "192.168.1.33"]
    }
}

# ссылка запроса
$url = "https://your_domain/api/v2/vm/get/techvuln"

# токен 
$token = "your_token"

# Заголовки запроса
$headers = @{
   "Content-Type" = "application/json"
   "Authorization" = "Bearer $token"
}

# Тело запроса
$body = @{
    page = 2
    perPage = 5
    sorting = @{
        column = "severity"
        order = "desc"
    }
    filters = @{
        filterByIp = @{
          enable = $true
          value = @("192.168.50.11", "87.250.250.242")
        }
    }
} | ConvertTo-Json -Depth 5

# Отправляем запрос
Invoke-WebRequest -Method Post -Uri $url -Headers $headers -Body $body

{  
    "page": 2,  
    "perPage": 5,  
    "sorting": {    
        "column": "severity",    
        "order": "desc"  
    },  
    "filters": {    
        "filterByIp": {      
            "enable": true,      
            "value": ["192.168.50.11", "87.250.250.242"]    
        }  
    }
}

• id, uuid - идентификаторы записи;
• name - имя уязвимости;
• cpe - cpe уязвимости;
• integral - интегральная величина критичности;
• severity - severity уязвимости;
• ip_count - количество хостов на которых есть эта уязвимость.

"pagination": {
    "currentPage": 2,
    "prevPage": "https://localhost/api/v2/vm/get/techvuln?page=1",
    "nextPage": null,
    "totalPage": 2
  },
  "total": 10,
  "objects": [
    {
      "id": 34,
      "uuid": "nessus-97861",
      "name": "Network Time Protocol (NTP) Mode 6 Scanner",
      "cpe": "",
      "integral": 3,
      "severity": 3,
      "ip_count": 1
    },
    {
      "id": 51,
      "uuid": "qualys-13162",
      "name": "Session Cookie Does Not Contain the "Secure" Attribute",
      "cpe": "",
      "integral": 2,
      "severity": 2,
      "ip_count": 1
    },

   #...
}

Импорт уязвимостей (JSON)

Content-Type: application/json
Authorization: Bearer your_token

• uuid - необязательное поле, уникальный идентификатор уязвимости. Если не указан uuid, то он формируется на основанииname;
• scanner - обязательное поле, имя сканера, если его нет, то просто придумать любое название;
• name - обязательное поле, название уязвимости;
• desc -  обязательное поле, описание уязвимости;
• solution -  обязательное поле, решение уязвимости;
• severity -  обязательное поле, серьезность/приоритет уязвимости;
• is_exploit - обязательное поле, существование эксплойта;
• ip -  обязательное поле, хост, на котором обнаружена уязвимость;
• hostname - необязательное поле,  имя хоста уязвимости;
• group - необязательное поле,  группа в которую входит уязвимость (CVE, KLA, ...);
• url - необязательное поле, ссылка на подробное описание уязвимости/

# URL запроса, подставьте домен вашего сервера
$url = "https://your_domain/api/v2/vm/push/techvuln"

# Подставьте ваш токен
$token = "TOKEN"

# Тело запроса в формате JSON
$body = @{
    scanner = "kas"
    name = "KLA10001"
    desc = "Описание уязвимости"
    solution = "Решение уязвимости"
    severity = 4
    is_exploit = 1
    ip = "192.168.0.1"
} | ConvertTo-Json

# Заголовки запроса
$headers = @{
    "Content-Type" = "application/json"
    "Authorization" = "Bearer $token" 
}

# Выполнение POST-запроса
try {
    $response = Invoke-RestMethod -Uri $url -Method Post -Body $body -Headers $headers

    # Вывод ответа сервера
    Write-Host "Ответ сервера:"
    $response | ConvertTo-Json | Write-Host

} catch {
    # Обработка ошибок
    Write-Host "Ошибка при выполнении запроса:"
    $_.Exception.Message | Write-Host
}

Импорт уязвимостей (файл)

Accept: application/json
Content-Type: multipart/form-data; boundary=your_boundary
Authorization: Bearer your_token

• file - обязательное поле, максимальный размер ограничен 200мб;
• asset - необязательное поле, необходимо указать uuid актива, если нужно привязать уязвимости к активу.

# путь к файлу который вы хотите загрузить
$filePath = "/your_path/nmap.xml"

# URL запроса, подставьте домен вашего сервера
$url = "https://your_domain/api/v2/vm/push/file"

# Подставьте ваш токен
$token = "TOKEN"

# Создаем границу (boundary)
$boundary = [System.Guid]::NewGuid().ToString()

# Читаем содержимое файла
$fileContent = [System.IO.File]::ReadAllBytes($filePath)

# Формируем тело запроса
$body = @"
--$boundary
Content-Disposition: form-data; name="file"; filename="nmap.xml"

$([System.Text.Encoding]::UTF8.GetString($fileContent))
--$boundary--
"@

# Создаем заголовки
$headers = @{
    "Accept" = "application/json"
    "Authorization" = "Bearer $token"
    "Content-Type" = "multipart/form-data; boundary='"$boundary'""
}

# Отправляем запрос
Invoke-WebRequest -Uri $url -Method Post -Body $body -Headers $headers

• code - код нашей внутренней ошибки, который будет описан в документации;
• message -  общее сообщение об ошибке, которое описывает ее суть;
• errors - техническая информация об ошибке. Например, какие права нужны для токена и какие у него есть сейчас;
• help - ссылка на документацию с решением/описанием ошибки, номер которой указан в поле code. 

{
  "code": "PR_001",
  "message": "The token doesnt have the required permissions",
  "errors": {
    "required_permissions": [
      "index",
      "import"
    ],
    "available_permissions": [
      "create",
      "import",
      "update"
    ]
  },
  "help": "https://localhost/help/api"
}

Валидация (VL)

{
  "code": "VL_001",
  "message": "Request validation failed",
  "errors": {
    "template": [
      "Import template not found"
    ]
  },
  "help": "https://localhost/help/api"
}

{
  "code": "VL_002",
  "message": "Invalid filter parameters",
  "errors": [],
  "help": "https://localhost/help/api"
}

Права доступа (PR)

Authorization: Bearer your_bearer_token

{
  "code": "PR_001",
  "message": "Token not found",
  "errors": {
    "token": "hello_securitm"
  },
  "help": "https://localhost/help/api"
}

{
  "code": "PR_002",
  "message": "Client is not in IP white list",
  "errors": {
    "ip": "192.168.0.1"
  },
  "help": "https://localhost/help/api"
}

Массив ошибок: показываем IP с которого делают запрос.{
  "code": "PR_003",
  "message": "The token doesnt have the required permissions",
  "errors": {
    "required_permissions": [
      "index"
    ],
    "available_permissions": [
      "create",
      "import",
      "update"
    ]
  },
  "help": "https://localhost/help/api"
}

{
  "code": "PR_004",
  "message": "Import operation denied for this scanner",
  "errors": {
    "scanner": "nessus"
  },
  "help": "https://localhost/help/api"
}

{
  "code": "PR_005",
  "message": "Import operation denied for this template",
  "errors": {
    "template": "Базовый импорт"
  },
  "help": "https://localhost/help/api"
}

{
  "code": "PR_006",
  "message": "Not enough permissions to import with this template",
  "errors": {
    "required_permissions": [
      "create",
      "update",
      "import"
    ],
    "available_permissions": [
      "import",
      "update"
    ]
  },
  "help": "https://localhost/help/api"
}

Типы активов (AT)

{
  "code": "AT_001",
  "message": "Assettype not found",
  "errors": ["assettype" => "os"],
  "help": "https://localhost/help/api"
}

Шаблоны импорта (IT)

{
  "code": "IT_001",
  "message": "Import template not found. Check private or community  hostInventory template",
  "errors": [],
  "help": "https://localhost/help/api"
}

Файловая система (FS)

{
  "code": "FS_001",
  "message": "Failed to save the uploaded file",
  "errors": [],
  "help": "https://localhost/help/api"
}

{
  "code": "FS_002",
  "message": "Invalid file structure",
  "errors": [],
  "help": "https://localhost/help/api"
}

Активы (AS)

{
  "code": "AS_001",
  "message": "No assets available for import",
  "errors": [],
  "help": "https://localhost/help/api"
}

{
  "code": "AS_002",
  "message": "Invalid assets data structure",
  "errors": [],
  "help": "https://localhost/help/api"
}