Guardd

Обнаружение поведенческих аномалий для Linux на основе eBPF и машинного обучения.

Guardd изучает, как обычно ведёт себя хост Linux, и отмечает активность, отличающуюся от этой базовой линии. Датчики ядра собирают запуски процессов и попытки исходящих TCP-соединений; Isolation Forest оценивает полученные одноминутные окна активности. Оповещения включают оценку, поведенческий контекст и пояснения, помогающие в расследовании.

Фоновый демон отвечает за сбор, обучение и обнаружение. Графический интерфейс и терминальный интерфейс позволяют просматривать оповещения и использование ресурсов, пока демон продолжает работу.

Статус: экспериментальный, в активной разработке. Качество обнаружения зависит от рабочей нагрузки, базовой линии и настроек чувствительности.

Установка · Использование · Конфигурация · Как это работает · Обновление · Устранение неполадок

Возможности

• Телеметрия ядра: имена процессов, пути к исполняемым файлам, пользователи, идентификаторы родительских процессов, а также исходящие IPv4 TCP-назначения и порты.
• Поведенческое обнаружение: количество активности, разнообразие и новизна, оцениваемые относительно фиксированной эталонной базовой линии.
• Автоматический жизненный цикл: первоначальный сбор, обучение модели, обнаружение, еженедельное переобучение и перезагрузка модели в одной службе systemd.
• Постоянные оповещения: хранение в SQLite с оценками, уровнем серьёзности, пояснениями, сводками признаков и контекстом; оповещения также выводятся в виде JSON с разделителями-переводами строк.
• Графический интерфейс: страницы «Обзор» и «Оповещения», поиск, фильтры по уровню серьёзности и времени, детальный просмотр оповещений и автоматическое обновление.
• Видимость системы: состояние службы, использование CPU и памяти, PID, время работы, информация о хосте и ядре, размер окна агрегации и актуальность телеметрии.
• Интеграция с рабочим столом: элемент меню приложений Guardd и значок пингвина.
• Доступ из терминала: curses TUI и команды для сбора, обучения, оценки и просмотра телеметрии напрямую.

Скриншоты

Обзор рабочего стола

Исследование оповещений

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

Терминальный интерфейс

Установка

Требования

Предоставляемый установщик использует apt-get и systemd. Ubuntu 24.04 LTS — практичная отправная точка; системам Debian нужны эквивалентные пакеты. Другие дистрибутивы требуют ручной установки зависимостей.

• Python 3.11 или новее, доступный как python3. Python 3.10 по умолчанию в Ubuntu 22.04 не соответствует требованию пакета.
• Ядро Linux с eBPF, BTF в /sys/kernel/btf/vmlinux и необходимыми точками трассировки процессов и сокетов.
• Clang/LLVM, заголовки разработки libbpf, libelf, инструментальная цепочка сборки C и bpftool для генерации заголовков ядра и скелетов BPF.
• Права root для установки службы и запуска датчиков.
• Графический сеанс рабочего стола для опционального GUI на PySide6.

В Ubuntu установите Git и инструменты ядра перед запуском установщика:```bash sudo apt-get update sudo apt-get install -y git linux-tools-common "linux-tools-$(uname -r)" python3 --version bpftool version test -r /sys/kernel/btf/vmlinux && echo "Kernel BTF available"

Пакет kernel-tools должен соответствовать вашему работающему ядру. В Debian `bpftool`
доступен как отдельный пакет. Установщик предоставляет остальные зависимости для сборки и
Python, но не устанавливает `bpftool` явно.

### Установка демона и графического интерфейса```bash
git clone https://github.com/benny-e/guardd.git
cd guardd
sudo bash install.sh --gui

Для headless-установки вместо этого выполните sudo bash install.sh.

Установщик копирует приложение в /opt/guardd, создаёт его виртуальное окружение, собирает eBPF-коллектор, устанавливает /usr/local/bin/guardd и включает guardd.service при загрузке. Он не запускает службу. С флагом --gui он также устанавливает зависимости среды выполнения Qt, ярлык рабочего стола и значок.

Настройте установленные пути

Перед первым запуском откройте установленный файл конфигурации:```bash sudoedit /opt/guardd/config.toml

Установите его раздел `[paths]` в абсолютные пути:```toml
[paths]
sensor_path = "/opt/guardd/ebpf/guardd"
db_path = "/opt/guardd/data/features.db"
model_path = "/opt/guardd/data/model.bundle"

Конфигурация репозитория использует относительные пути. Они работают из рабочего каталога сервиса /opt/guardd, но десктопный лаунчер может запускаться из другого места. Абсолютные пути позволяют демону, GUI и CLI использовать одни и те же данные.

Проверьте настройки обучения в разделе Configuration, затем запустите:```bash sudo systemctl start guardd.service systemctl status guardd.service sudo journalctl -u guardd.service -f

Первый запуск собирает данные до того, как модель станет доступна. Активный сервис всё ещё может находиться в этой фазе сбора; проверьте его логи для обучения и обнаружения.

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

### Графический интерфейс для настольных систем

Откройте **Guardd** из меню приложений или выполните:```bash
guardd gui

Запускайте GUI от имени обычного пользователя рабочего стола. Он читает существующую базу данных и обновляется каждые пять секунд. При закрытии демон продолжает работать.

Страница	Что можно делать
Обзор	Проверяйте состояние службы, оповещения за сегодня, доступность файла модели, использование CPU/памяти, PID, время работы, сведения о хосте/ядре, размер 60-секундного окна и последнюю телеметрию. Выберите недавнее оповещение, чтобы изучить его.
Оповещения	Ищите по именам процессов, путям, назначениям и причинам; фильтруйте по уровню серьёзности и за последние 24 часа, 7 дней, 30 дней или за всё время; выберите оповещение, чтобы просмотреть его оценку, порог, пояснения, активность и контекст.

Используйте Refresh для немедленного обновления. Время отображается в вашем местном часовом поясе, а суточные итоги на странице «Обзор» охватывают местный календарный день независимо от фильтров.

Чтобы выбрать другую базу данных или увеличить отображаемый лимит оповещений:```bash guardd gui --db-path /opt/guardd/data/features.db --model-path /opt/guardd/data/model.bundle --limit 500

GUI — это средство просмотра только для чтения: сбор, обучение и управление службой выполняются через демон и CLI. Доступность модели означает, что файл существует, а не то, что его содержимое корректно или что обнаружение запущено. GUI не загружает pickled-модели. Метрики ресурсов охватывают всю службу systemd, включая сенсор; 100% CPU соответствует одному логическому ядру. Для первого показания CPU требуется два замера.