GraphQL API

Об API

API системы R-Vision SIEM, основанный на технологии GraphQL, представляет собой комплексный интерфейс для выполнения запросов и манипуляций с данными в рамках системы. Основное предназначение API — обеспечение доступа к основному функционалу системы, что включает в себя поиск событий, управление элементами экспертизы, изменение статусов и уровней угроз оповещений, а также взаимодействие с каталогами элементов экспертизы и экспорт данных.

Об API-токенах

Взаимодействие с API осуществляется через HTTP-запросы методами POST для отправки GraphQL-запросов и мутаций. Каждый запрос требует наличия авторизационного токена в заголовке запроса. API-токен выпускается системой посредством функционала ботов. Бот — учетная запись, предназначенная для автоматизированного взаимодействия с системой через API-запросы. При создании бота, ему автоматически присваивается API-токен.

О GraphQL

GraphQL представляет собой язык запросов для API, обладающий следующими характеристиками:

Спецификация: определяет правила валидации схемы на стороне сервера API, а также валидность вызовов клиента на основе этой схемы.
Строгая типизация: схема GraphQL строго типизирована, описывая типы данных и отношения между объектами, что обеспечивает предсказуемость и точность ответов API.

Иерархичность: структура запросов и ответов GraphQL отражает иерархическую структуру данных, позволяя клиентам получать именно те данные, которые необходимы, в одном запросе.
Уровень приложения: GraphQL функционирует на уровне приложения, не завися от конкретных технологий хранения данных. Графическая структура запросов и ответов описывается в схеме API, определяющей объекты и их связи.

Начало работы

Для интеграции с API системы R-Vision SIEM рекомендуется выполнение ряда действий, таких как подготовка окружения, получение токена и авторизация.

Подготовка и настройка окружения

Установите и настройте необходимые инструменты, которые поддерживают формирование и отправку GraphQL запросов. Например, такие, как Postman, Insomnia или GraphQL IDE.

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

Доступ к функциональности API системы R-Vision SIEM требует аутентификации с использованием токена авторизации. Токен — это уникальный цифро-буквенный код, представленный в формате JWT (JSON Web Token), который включается в каждый запрос через HTTP заголовок Authorization.

Токен можно получить, создав учетную запись с типом Бот в веб-интерфейса системы R-Vision SIEM.

Для выполнения запросов к API, необходимо включить следующие HTTP заголовки:

Authorization: заголовок, содержащий токен авторизации в формате JWT (JSON Web Token). Токен предоставляет информацию о пользователе и его правах доступа.
x-tenant-id: заголовок, указывающий идентификатор тенанта.

Токен передается в заголовке Authorization HTTP-запроса при обращении к API.

Bearer не является частью самого токена и добавляется в заголовок запроса в качестве префикса перед самим токеном для указания схемы аутентификации.

Example 1. Необходимые HTTP заголовки для выполнения запросов:

{
  "Authorization": "Bearer <ваш_токен_доступа>",
  "x-tenant-id": "00000000-0000-0000-0000-000000000000"
}

Где <ваш_токен_доступа> — это актуальный токен доступа, полученный после аутентификации в системе R-Vision SIEM.

Example 2. Пример HTTP заголовков:

{
  "Authorization": "Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...,
  "x-tenant-id": "99311ef1-32a1-4b2d-9d38-7613be5e...."
}

Выполнение первого запроса

Пример запроса на получение детальной информации об элементе экспертизы:

query {
  expertise(id: "uniqueExpertiseId") {
    id
    sourceId
    folderId
    type
    name
    description
    draft
    author
    status
    tags
    version
    severity
    createdAt
    updatedAt
    __typename
  }
}

В этом запросе используется параметр:

id: уникальный идентификатор элемента экспертизы, информацию о котором необходимо получить.

Возвращаемый тип Expertise

Параметр

Описание

id

Уникальный идентификатор элемента экспертизы.

sourceId

Идентификатор исходного объекта, если применимо.

folderId

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

type

Тип элемента экспертизы.

name

Название элемента экспертизы.

description

Описание элемента экспертизы.

draft

Указывает, является ли объект черновиком.

author

Автор элемента экспертизы. Указывается автоматически на основе данных пользователя, выполнившего мутацию.

status

Статус элемента экспертизы.

tags

Массив тегов, ассоциированных с объектом.

version

Версия элемента экспертизы.

severity

Уровень серьезности элемента экспертизы.

createdAt

Дата и время создания объекта.

updatedAt

Дата и время последнего обновления объекта.

__typename

Название типа объекта в системе GraphQL.

Выполнение запросов

Для выполнения запросов GraphQL, учитывая, что операции GraphQL состоят из многострочного JSON, рекомендуется использовать GraphQL Explorer. В качестве альтернативы можно использовать curl или любую другую HTTP-совместимую библиотеку. Все запросы GraphQL, будь то запросы (queries), мутации (mutations) или подписки (subscriptions) передаются в теле POST-запроса в формате JSON.

Пример использования curl для выполнения GraphQL запроса:

curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" -H "x-tenant-id: YOUR_TENANT_ID" -X POST -d " \
 { \
   \"query\": \"query { yourQueryHere }\" \
 } \
" https://your-rvision-siem-domain/api/graphql

В этом примере:

YOUR_ACCESS_TOKEN должен быть заменен на ваш фактический токен доступа к системе R-Vision SIEM.
YOUR_TENANT_ID должен быть заменен на идентификатор вашего тенанта в системе.
yourQueryHere должен быть заменен на ваш конкретный запрос GraphQL, например, запрос на получение списка событий или информации о специфическом объекте.
URL your-rvision-siem-domain/api/graphql представляет собой конечную точку для доступа к GraphQL API вашей системы R-Vision SIEM и должен быть заменен на актуальный URL вашего API.

Важно корректно экранировать специальные символы в теле JSON-запроса для обеспечения его правильной обработки сервером. Внешние двойные кавычки и экранированные внутренние двойные кавычки помогают избежать ошибок при разборе запроса.

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