benny-e/guarddML 기반 리눅스 머신용 행동 기반 엔드포인트 탐지 시스템
eBPF와 머신 러닝으로 구동되는 Linux용 행위 기반 이상 탐지.
Guardd는 Linux 호스트가 평소 어떻게 동작하는지 학습하고, 그 기준선과 다른 활동을 표시합니다. 커널 센서가 프로세스 실행과 아웃바운드 TCP 연결 시도를 수집하고, Isolation Forest가 그로부터 만들어진 1분 단위 활동 윈도우를 점수화합니다. 경고에는 점수, 행위 맥락, 그리고 조사를 돕기 위한 설명이 포함됩니다.
백그라운드 데몬이 수집, 학습, 탐지를 담당합니다. 데스크톱 GUI와 터미널 인터페이스를 통해 데몬이 계속 실행되는 동안 경고와 리소스 사용량을 확인할 수 있습니다.
상태: 실험적이며 활발히 개발 중입니다. 탐지 품질은 워크로드, 기준선, 민감도 설정에 따라 달라집니다.
설치 · 사용법 · 설정 · 동작 방식 · 업데이트 · 문제 해결
데스크톱 스크린샷은 샘플 경고와 시뮬레이션된 서비스 상태를 사용합니다.
제공된 설치 프로그램은 apt-get과 systemd를 사용합니다. Ubuntu 24.04 LTS가
실용적인 출발점이며, Debian 시스템에는 이에 상응하는 패키지가 필요합니다. 다른
배포판은 의존성을 수동으로 설치해야 합니다.
python3로 사용 가능한 Python 3.11 이상. Ubuntu 22.04의 기본 Python
3.10은 패키지 요구 사항을 충족하지 않습니다./sys/kernel/btf/vmlinux의 BTF, 그리고 필요한 프로세스 및 소켓
트레이스포인트를 지원하는 Linux 커널.bpftool.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`을 명시적으로 설치하지는 않습니다.
### 데몬 및 데스크톱 GUI 설치```bash
git clone https://github.com/benny-e/guardd.git
cd guardd
sudo bash install.sh --gui
헤드리스 설치의 경우 대신 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
첫 실행은 모델을 사용할 수 있기 전에 데이터를 수집합니다. 활성 서비스는 여전히 이 수집 단계에 있을 수 있으므로, 로그에서 학습 및 탐지 여부를 확인하십시오.
## 사용법
### 데스크톱 GUI
애플리케이션 메뉴에서 **Guardd**를 열거나 다음을 실행하십시오:```bash
guardd gui
일반 데스크톱 사용자로 GUI를 실행하십시오. GUI는 기존 데이터베이스를 읽고 5초마다 새로 고칩니다. GUI를 닫아도 데몬은 계속 실행됩니다.
| 페이지 | 할 수 있는 작업 |
|---|---|
| 개요 | 서비스, 오늘의 경보, 모델 파일 가용성, CPU/메모리 사용량, PID, 가동 시간, 호스트/커널 세부 정보, 60초 윈도우 크기, 최근 텔레메트리를 확인합니다. 최근 경보를 선택하여 검사합니다. |
| 경보 | 프로세스 이름, 경로, 목적지, 사유를 검색하고, 심각도 및 최근 24시간, 7일, 30일, 전체 기간으로 필터링하며, 경보를 선택하여 점수, 임계값, 설명, 활동, 컨텍스트를 확인합니다. |
즉시 업데이트하려면 새로 고침을 사용하십시오. 시간은 로컬 시간대를 사용하며, 개요의 일일 합계는 필터와 무관하게 로컬 달력 날짜를 기준으로 합니다.
다른 데이터베이스를 선택하거나 표시되는 경보 한도를 늘리려면:```bash guardd gui --db-path /opt/guardd/data/features.db --model-path /opt/guardd/data/model.bundle --limit 500
GUI는 읽기 전용 뷰어입니다. 수집, 학습, 서비스 제어는 데몬과 CLI를 통해 이루어집니다. 모델 가용성이란 파일이 존재한다는 의미일 뿐, 그 내용이 유효하다거나 탐지가 시작되었다는 의미는 아닙니다. GUI는 피클된 모델을 로드하지 않습니다. 리소스 지표는 센서를 포함한 전체 systemd 서비스를 포괄하며, CPU 100%는 논리 코어 하나를 나타냅니다. 첫 번째 CPU 판독값에는 두 개의 샘플이 필요합니다.
### 터미널 인터페이스```bash
sudo guardd tui
TUI는 2초마다 새로 고침되며 경고 세부 정보와 데몬 통계를 표시합니다.
GUI와 달리 쓰기 가능한 데이터베이스 연결을 통해 스토리지를 초기화합니다;
표준 root 소유 설치에서는 sudo가 필요할 수 있습니다.
| 키 | 동작 |
|---|---|
↑ / k, ↓ / j | 경고를 선택합니다. |
/ | 검색; Enter를 눌러 적용하거나 Esc를 눌러 취소합니다. |
r | 검색을 지우고 첫 번째 경고로 돌아갑니다. |
q / Esc | 종료합니다. |
sudo systemctl stop guardd.service sudo systemctl start guardd.service sudo systemctl restart guardd.service systemctl status guardd.service sudo journalctl -u guardd.service -n 100 --no-pager sudo journalctl -u guardd.service -f
구성 파일을 편집한 후 서비스를 재시작하십시오. 부팅 시 자동 시작을 활성화하거나 비활성화하려면 `sudo systemctl enable guardd.service` 또는
`sudo systemctl disable guardd.service`를 사용하십시오.
### CLI 및 수동 작업
한 번에 하나의 수집기만 실행하십시오. 수동으로 수집하거나 탐지하기 전에 systemd 서비스를 중지하고, 모델을 학습시키기 전에 수동 수집기를 중지하십시오.
| 명령 | 목적 |
| --- | --- |
| `guardd` 또는 `guardd daemon` | 자동 수집 → 학습 → 탐지 라이프사이클을 실행합니다. |
| `guardd daemon --mode collect` | 자동 학습 없이 윈도우를 수집합니다. |
| `guardd daemon --mode detect` | 기존의 호환되는 모델을 사용하여 윈도우를 채점합니다. |
| `guardd collect` | 라이브 윈도우를 SQLite에 수집합니다. |
| `guardd train` | 저장된 윈도우로 모델을 학습시키고 요약을 출력합니다. |
| `guardd detect` | 라이브 윈도우를 채점하고 경고를 발생시킵니다. |
| `guardd ingest` | 디버깅을 위해 파싱된 센서 이벤트를 출력합니다. |
| `guardd gui` / `guardd tui` | 데스크톱 또는 터미널 인터페이스에서 경고를 탐색합니다. |
표준 설치에서 수동 워크플로는 다음과 같습니다:```bash
sudo systemctl stop guardd.service
sudo guardd collect --sensor-path /opt/guardd/ebpf/guardd --db-path /opt/guardd/data/features.db
# Press Ctrl+C after collecting enough representative activity.
sudo guardd train --db-path /opt/guardd/data/features.db --model-out /opt/guardd/data/model.bundle
sudo guardd detect --sensor-path /opt/guardd/ebpf/guardd --db-path /opt/guardd/data/features.db --model-path /opt/guardd/data/model.bundle
Ctrl+C를 눌러 수동 탐지를 중지한 다음, systemd 서비스를 재시작하여
백그라운드 작업을 재개하십시오. 포그라운드 자동 데몬의 경우
sudo guardd daemon을 사용하십시오. 원시 텔레메트리의 경우
sudo guardd ingest --sensor-path /opt/guardd/ebpf/guardd --pretty를 사용하십시오.
모든 명령에 --help를 추가하면 해당 옵션을 확인할 수 있습니다. 탐지는
--print-all-scores, --print-features, --print-windows, --no-store를 지원합니다.
--no-store는 feature-window 쓰기를 비활성화합니다. 탐지된 이상은 여전히 저장됩니다.
Guardd는 다음 순서로 처음 존재하는 파일을 로드합니다:
./guardd.toml./etc/guardd/config.toml./opt/guardd/config.toml.파일은 병합되지 않습니다. 체크아웃의 config.toml은 템플릿이며,
자동으로 발견되는 개발 구성이 아닙니다. 로컬 설정의 경우 이를
guardd.toml로 복사하고 경로를 조정하십시오.
다음은 빈번한 부트스트랩 시도와 더 긴 초기 학습 기간을 가진 설치된 시스템의 예입니다:```toml [paths] sensor_path = "/opt/guardd/ebpf/guardd" db_path = "/opt/guardd/data/features.db" model_path = "/opt/guardd/data/model.bundle"
[logging] debug = false
[daemon] mode = "auto" bootstrap_retry_seconds = 600 retrain_interval_seconds = 604800 print_windows = false print_features = false print_all_scores = false no_store = false
[train] min_training_rows = 1380 baseline_fraction = 0.2 limit = 50000 contamination = 0.01 n_estimators = 200 random_state = 42 threshold_percentile = 10.0
[gui] limit = 200