guardd

Обнаружение аномалий поведения на основе машинного обучения для Linux с использованием eBPF + Isolation Forest

Guardd собирает низкоуровневые системные события (выполнение процессов, сетевая активность), агрегирует их в векторы признаков с временными окнами и обнаруживает аномальное поведение с помощью модели машинного обучения.

Guardd ориентирован на обнаружение неизвестных угроз

[!WARNING] Этот проект всё ещё в разработке
Функции и точность обнаружения активно улучшаются
Отзывы, предложения и вклад приветствуются

Как это работает

guardd работает как единый systemd-сервис, управляющий полным жизненным циклом сбора данных, обучения и обнаружения.

При запуске:

Если модель не существует, guardd начинает сбор базовых поведенческих данных
Он собирает данные за 1 день (по умолчанию) для первоначального обучения
После успешного обучения он автоматически переключается в режим обнаружения

Во время работы:

Активность системы непрерывно агрегируется в временные окна и преобразуется в векторы признаков
Каждое окно оценивается обученной моделью Isolation Forest
Аномалии выводятся в формате NDJSON

Постоянно:

Модель автоматически переобучается раз в неделю
Обнаружение возобновляется сразу после переобучения с обновленной моделью

Установка

1. Клонирование репозитория

git clone https://github.com/benny-e/guardd.git
cd guardd

2. Запуск скрипта установки

sudo bash install.sh

Это сделает следующее:

Установка системных зависимостей
Копирование проекта в /opt/guardd
Создание виртуальной среды Python
Установка пакета
Сборка компонентов eBPF
Установка systemd-сервиса

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

Запуск службы

sudo systemctl start guardd.service

Проверка статуса

systemctl status guardd.service

Просмотр логов

journalctl -u guardd.service -f

Терминальный TUI

guardd включает терминальный интерфейс для просмотра последних оповещений и поиска аномалий

Для запуска: (после запуска guardd.service)

guardd tui

Запуск без systemd

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

Запуск полного демона

sudo guardd daemon

Запуск отдельных компонентов

Сбор данных:

sudo guardd collect

Обучение модели:

sudo guardd train

Обнаружение:

sudo guardd detect

Конфигурация

guardd поддерживает конфигурацию через файл config.toml.

По умолчанию демон ищет в:

/opt/guardd/config.toml

Пример

[daemon]
mode = "auto"
bootstrap_retry_seconds = 60
retrain_interval_seconds = 604800

[training]
min_training_rows = 1
contamination = 0.01
n_estimators = 200
threshold_percentile = 10.0

[paths]
db_path = "/opt/guardd/data/features.db"
model_path = "/opt/guardd/data/model.bundle"
guardd_path = "/opt/guardd/ebpf/guardd"

[daemon]

Управляет жизненным циклом guardd.

mode
-- "auto" → полный конвейер (сбор → обучение → обнаружение)
-- "collect" → только сбор данных
-- "detect" → только обнаружение (требуется модель)

bootstrap_retry_seconds
-- Как часто guardd пытается выполнить начальное обучение, когда модель отсутствует
-- На этом этапе guardd собирает данные и периодически приостанавливается для попытки обучения

retrain_interval_seconds
-- Как часто модель переобучается после начальной настройки
-- По умолчанию: 7 дней

[train]

Управляет поведением и требованиями модели.

min_training_rows
-- Минимальное количество окон признаков, необходимое для обучения
-- Если условие не выполнено, обучение завершается ошибкой и будет повторено позже

contamination
-- Ожидаемая доля аномалий в данных
-- Передается напрямую в Isolation Forest
-- Типичные значения: 0.01–0.05

n_estimators
-- Количество деревьев в Isolation Forest
-- Больше = выше точность, медленнее обучение

threshold_percentile
-- Определяет пороговое значение аномалии
-- Меньше = более агрессивное обнаружение

[paths]

Определяет пути для чтения/записи данных guardd.

db_path
-- База данных SQLite, хранящая векторы признаков и аномалии

model_path
-- Сериализованный пакет модели, используемый для обнаружения

guardd_path
-- Путь к бинарному файлу сборщика eBPF

Примечания

Значения конфигурации переопределяют стандартные значения CLI
Аргументы CLI могут всё же переопределять конфигурацию, если они указаны явно
Точность модели сильно зависит от качества обучающих данных. Более длительное обучение приведет к более точному детектору

Зависимости

python3
python3-venv
python3-pip
clang
llvm
libbpf-dev
libelf-dev
bpftool
build-essential
pkg-config
sqlite3