Операционная система ЗОСРВ «Нейтрино» > Руководство разработчика > Интерфейсы различных подсистем > Монитор аномальной активности (amon) > Общие сведения > Использование API сервиса amon

Использование API сервиса amon

Краткое руководство по использованию API сервиса amon

В этой главе:

Получение сведений об общем состоянии amon

Работа с объектами

Работа с оповещениями

Управление режимами работы amon

Дообучение на данных аномалий

Получение сведений об общем состоянии amon

Для получения общего состояния amon используется структура OutputDataSummary и команда devctl DCMD_AMON_GET_SUMMARY. Общее состояние amon включает в себя информацию о текущем общем уровне доверия, количестве захваченных объектов, количестве оповещений и о времени обработки данных (задержка). Пример использования этой команды приведён ниже.

#include <amon/api.h>
 
int main() {
    OutputDataSummary buf;
     
    // Подключаемся к менеджеру ресурсов
    int fd = open(AMON_DEV_NAME, O_RDWR);
     
    if (fd == -1) {
        std::cout << "Failed to open " << AMON_DEV_NAME << std::endl;
        exit(EXIT_FAILURE);
    }
     
    iov_t riov;
    SETIOV(&riov, &buf, sizeof(OutputDataSummary));
     
    // Отправляем команду
    int ret = devctlv(fd, DCMD_AMON_GET_SUMMARY, 0, 1, nullptr, &riov, nullptr);
     
    close(fd);
    if (ret != EOK) {
        std::cout << "Failed to execute command DCMD_AMON_GET_SUMMARY." << std::endl;
        exit(EXIT_FAILURE);
    }
}

Работа с объектами

Чтобы получить список захваченных объектов, используется структура ObjectData и команда devctl DCMD_AMON_GET_OBJECT_LIST. Сервис возвращает массив, содержащий список захваченных им объектов. Перед получением данных необходимо выделить память под массив. Размер этого массива определяется максимальным размером списка для хранения информации об объектах (параметр "object_list_max_size" в конфигурационном файле amon). Это значение можно получить с помощью команды devctl DCMD_AMON_GET_CONFIG. Пример получения списка объектов приведён ниже.

#include <amon/api.h>
 
int main() {
    ConfigData config;
    memset(&config, 0, sizeof(ConfigData));
     
    // Подключаемся к менеджеру ресурсов
    int fd = open(AMON_DEV_NAME, O_RDWR);
     
    if (fd == -1) {
        std::cout << "Failed to open " << AMON_DEV_NAME << std::endl;
        exit(EXIT_FAILURE);
    }
     
    iov_t riovc;
    SETIOV(&riovc, &config, sizeof(ConfigData));
     
    // получаем конфигурацию amon
    int ret = devctlv(fd, DCMD_AMON_GET_CONFIG, 0, 1, nullptr, &riovc, nullptr);
     
    if (ret != EOK) {
        close(fd);
        std::cout << "Failed to execute command DCMD_AMON_GET_CONFIG." << std::endl;
        exit(EXIT_FAILURE);
    }
     
    auto buf = new ObjectData[config.olistsize];
    memset(buf, 0, sizeof(ObjectData)*config.olistsize);
     
    iov_t riovo;
    SETIOV(&riovo, buf, sizeof(ObjectData)*config.olistsize);
     
    // выполняем команду
    ret = devctlv(fd, DCMD_AMON_GET_OBJECT_LIST, 0, 1, nullptr, &riovo, nullptr);
     
    close(fd);
    if (ret != EOK) {
        delete [] buf;
        std::cout << "Failed to execute command DCMD_AMON_GET_OBJECT_LIST." << std::endl;
        exit(EXIT_FAILURE);
    }
     
    for (int i = 0; i < Config.olistsize; i++) {
        if (buf[i].mode == 0xFF) {
            // Если список заполнен не до конца, после последнего элемента будет расположен ещё один элемент списка с полем mode равным 0xFF
            break;
        }
        /* Использование полей структуры buf[i] */
    }
}

Для того, чтобы получить информацию об объекте, используется управляющая структура AmonObjectQuery, структура ObjectData и команда devctl DCMD_AMON_GET_OBJECT_INFO. Информация об объекте включает в себя имя объекта, имя его класса, уровень доверия, уровень девиации, а также список анализируемых параметров. Пример использования этой команды приведён ниже.

#include <amon/api.h>
 
int main() {
    // Подключаемся к менеджеру ресурсов
    int fd = open(AMON_DEV_NAME, O_RDWR);
     
    if (fd == -1) {
        std::cout << "Failed to open " << AMON_DEV_NAME << std::endl;
        exit(EXIT_FAILURE);
    }
     
    AmonObjectQuery query;
    ObjectData object;
    memset(&object, 0, sizeof(ObjectData));
     
    query.oid = /* идентификатор объекта (ObjectID), информацию о котором необходимо получить */;
    query.cid = /* номер класса объекта (ClassID), информацию о котором необходимо получить */;
     
    iov_t siov, riov;
    SETIOV(&siov, &query, sizeof(AmonObjectQuery));
    SETIOV(&riov, &object, sizeof(ObjectData));
     
    // выполняем команду
    int ret = devctlv(fd, DCMD_AMON_GET_OBJECT_INFO, 2, 1, &siov, &riov, nullptr);
     
    close(fd);
    if (ret != EOK) {
        std::cout << "Failed to execute command DCMD_AMON_GET_OBJECT_INFO." << std::endl;
        exit(EXIT_FAILURE);
    }
}

Работа с оповещениями

Чтобы получить список оповещений, используется структура AlertData и команда devctl DCMD_AMON_GET_ALERT_LIST. Сервис возвращает массив, содержащий список оповещений об аномалиях. Перед получением данных необходимо выделить память под массив. Размер этого массива определяется максимальным размером списка для сообщений об аномалиях. (параметр "alert_list_max_size" в конфигурационном файле amon). Это значение можно получить с помощью команды devctl DCMD_AMON_GET_CONFIG. Пример получения списка объектов приведён ниже.

#include <amon/api.h>
 
int main() {
    ConfigData config;
    memset(&config, 0, sizeof(ConfigData));
     
    // Подключаемся к менеджеру ресурсов
    int fd = open(AMON_DEV_NAME, O_RDWR);
     
    if (fd == -1) {
        std::cout << "Failed to open " << AMON_DEV_NAME << std::endl;
        exit(EXIT_FAILURE);
    }
     
    iov_t riov;
    SETIOV(&riov, &config, sizeof(ConfigData));
     
    // получаем конфигурацию amon
    int ret = devctlv(fd, DCMD_AMON_GET_CONFIG, 0, 1, nullptr, &riov, nullptr);
     
    if (ret != EOK) {
        close(fd);
        std::cout << "Failed to execute command DCMD_AMON_GET_CONFIG." << std::endl;
        exit(EXIT_FAILURE);
    }
     
    auto buf = new AlertData[config.alistsize];
    memset(buf, 0, sizeof(AlertData)*config.alistsize);
     
    SETIOV(&riov, buf, sizeof(AlertData)*config.alistsize);
     
    // выполняем команду
    ret = devctlv(fd, DCMD_AMON_GET_ALERT_LIST, 0, 1, nullptr, &riov, nullptr);
     
    close(fd);
    if (ret != EOK) {
        delete [] buf;
        std::cout << "Failed to execute command DCMD_AMON_GET_ALERT_LIST." << std::endl;
        exit(EXIT_FAILURE);
    }
     
    for (int i = 0; i < Config.alistsize; i++) {
        if (buf[i].aid == 0) {
            // Если список заполнен не до конца, после последнего элемента будет расположен ещё один элемент списка с полем aid равным 0
            break;
        }
        /* Использование полей структуры buf[i] */
    }
}

Для того, чтобы получить информацию об оповещении, используется структура AlertData и команда devctl DCMD_AMON_GET_ALERT_INFO. Информация об оповещении включает в себя дату и время возникновения оповещения, а также полный слепок состояния объекта на момент возникновения оповещения. Пример использования этой команды приведён ниже.

#include <amon/api.h>
 
int main() {
    uint32_t aid = /* идентификатор оповещения (AlertID) */
     
    // Подключаемся к менеджеру ресурсов
    int fd = open(AMON_DEV_NAME, O_RDWR);
     
    if (fd == -1) {
        std::cout << "Failed to open " << AMON_DEV_NAME << std::endl;
        exit(EXIT_FAILURE);
    }
     
    AlertData alert;
    memset(&alert, 0, sizeof(AlertData));
     
    iov_t siov, riov;
    SETIOV(&siov, &aid, sizeof(uint32_t));
    SETIOV(&riov, &alert, sizeof(AlertData));
     
    // выполняем команду
    int ret = devctlv(fd, DCMD_AMON_GET_ALERT_INFO, 1, 1, &siov, &riov, nullptr);
     
    close(fd);
    if (ret != EOK) {
        std::cout << "Failed to execute command DCMD_AMON_GET_OBJECT_INFO." << std::endl;
        exit(EXIT_FAILURE);
    }
     
    if (!alert.aid) {
      std::cout << "Alert with ID " << aid << " not found" << std::endl;
      exit(EXIT_FAILURE);
    }
}

Управление режимами работы amon

Для того, чтобы изменить режим работы amon, используется управляющая структура AmonModeControl и команда devctl DCMD_AMON_SET_MODE. Изменение режима работы предполагает переключение сервиса в режим обучения или анализа, как для всех объектов, так и для какого-то конкретного. Пример использования этой команды приведён ниже.

#include <amon/api.h>
 
int main() {
    // Подключаемся к менеджеру ресурсов
    int fd = open(AMON_DEV_NAME, O_RDWR);
     
    if (fd == -1) {
        std::cout << "Failed to open " << AMON_DEV_NAME << std::endl;
        exit(EXIT_FAILURE);
    }
     
    AmonModeControl modectl;
    modectl.mode = /* режим работы (AMON_MODE_LEARN или AMON_MODE_ANALYZE) */;
    modectl.oid = /* ObjectID */;
    modectl.cid = /* ClassID */;
     
    iov_t siov;
    SETIOV(&siov, &modectl, sizeof(AmonModeControl));
     
    // выполняем команду
    int ret = devctlv(fd, DCMD_AMON_SET_MODE, 1, 0, &siov, nullptr, nullptr);
     
    if (ret != EOK) {
        std::cout << "Failed to execute command DCMD_AMON_SET_MODE." << std::endl;
        exit(EXIT_FAILURE);
    } else {
        if (!oid) std::cout << "All objects";
        else std::cout << "Object width id " << oid << " and class " << cid;
        if (mode == 0) std::cout << " switched to learning mode" << std::endl << std::endl;
        else std::cout << " switched to recognition mode" << std::endl << std::endl;
    }
}

Дообучение на данных аномалий

Для дообучения сервиса amon на основе аномалий используется управляющая структура AmonLearnAlert и команда devctl DCMD_AMON_LEARN_ALERT. Пример использования этой команды приведён ниже.

#include <amon/api.h>
 
int main() {
    // Подключаемся к менеджеру ресурсов
    int fd = open(AMON_DEV_NAME, O_RDWR);
     
    if (fd == -1) {
        std::cout << "Failed to open " << AMON_DEV_NAME << std::endl;
        exit(EXIT_FAILURE);
    }
     
    AmonLearnAlert alearn;
    alearn.aid = /* идентификатор оповещения об аномальной активности, которую надо принять как доверенную, выполнив дообучение */;
     
    iov_t siov;
    SETIOV(&siov, &alearn, sizeof(AmonLearnAlert));
     
    // выполняем команду
    int ret = devctlv(fd, DCMD_AMON_LEARN_ALERT, 1, 0, &siov, nullptr, nullptr);
     
    if (ret != EOK) {
        std::cout << "Failed to execute command DCMD_AMON_LEARN_ALERT." << std::endl;
        exit(EXIT_FAILURE);
    } else {
        std::cout << "Amon accepted anomaly with id " << alearn.aid << std::endl;
    }
}

Предыдущий раздел: перейти