guardd

머신러닝 기반 리눅스용 행동 이상 탐지 (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에는 최근 알림을 탐색하고 이상 징후를 검색하기 위한 터미널 UI가 포함되어 있습니다

실행 방법: (guardd.service 시작 후)

guardd tui

systemd 없이 실행하기

guardd를 systemd 서비스를 설치하지 않고 명령줄에서 직접 실행할 수 있습니다. 다른 init 시스템과 함께 실행되도록 구성할 수 있습니다

전체 데몬 실행

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