基于 eBPF 和机器学习的 Linux 行为异常检测。
Guardd 会学习 Linux 主机的正常行为模式，并标记出与该基线不同的活动。 内核传感器收集进程执行和出站 TCP 连接尝试；Isolation Forest 对生成的 一分钟活动窗口进行评分。告警包含评分、行为上下文和解释， 以帮助你进行调查。
后台守护进程负责收集、训练和检测。桌面 GUI 和终端界面让你可以在守护进程继续运行时检查告警和资源使用情况。
状态： 实验性，正在积极开发中。检测质量取决于 工作负载、基线和灵敏度设置。
安装 · 使用 · 配置 · 工作原理 · 更新 · 故障排除
桌面截图使用示例告警和模拟的服务状态。
提供的安装程序使用 apt-get 和 systemd。Ubuntu 24.04 LTS 是一个实用的
起点；Debian 系统需要等效的软件包。其他发行版
需要手动安装依赖项。
python3 形式提供。Ubuntu 22.04 的默认 Python
3.10 不满足软件包要求。/sys/kernel/btf/vmlinux，以及所需的
进程和套接字跟踪点。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。它会读取现有数据库并每五秒刷新一次。关闭它后守护进程仍在运行。
| 页面 | 您可以做什么 |
|---|---|
| Overview | 检查服务、今日告警、模型文件可用性、CPU/内存使用情况、PID、运行时间、主机/内核详细信息、60 秒窗口大小以及最近的遥测数据。选择一条最近的告警以查看详情。 |
| Alerts | 搜索进程名称、路径、目标地址和原因；按严重程度以及最近 24 小时、7 天、30 天或全部时间进行筛选；选择一条告警以查看其评分、阈值、解释、活动和上下文。 |
使用 Refresh 立即更新。时间使用您的本地时区，Overview 的每日总计覆盖本地日历日，与筛选条件无关。
要选择不同的数据库或增加显示的告警数量上限：```bash guardd gui --db-path /opt/guardd/data/features.db --model-path /opt/guardd/data/model.bundle --limit 500
GUI 是一个只读查看器：采集、训练和服务控制均通过守护进程和 CLI 进行。模型可用仅表示文件存在，并不表示其内容有效或检测已启动。GUI 不会加载 pickle 模型。资源指标覆盖整个 systemd 服务，包括传感器；100% CPU 表示一个逻辑核心。首次 CPU 读数需要两个采样。
### 终端界面```bash
sudo guardd tui
TUI 每两秒刷新一次，并显示告警详情和守护进程统计信息。
与 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 禁用特征窗口写入；检测到的异常仍会被存储。
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
[tui] limit = 200
| 设置 | 含义 |
| --- | --- |
| `[paths] sensor_path` | 编译后的 eBPF 采集器可执行文件。 |
| `[paths] db_path` | 用于特征窗口和告警的 SQLite 数据库。 |
| `[paths] model_path` | 检测所使用的已训练模型包。 |
| `[daemon] mode` | 默认自动生命周期。使用 `guardd daemon --mode ...` 显式选择 `collect` 或 `detect`；请参阅下方的解析器优先级说明。 |
| `[daemon] bootstrap_retry_seconds` | 采集期间初始训练尝试之间的延迟。仓库配置使用 `82800` 秒（23 小时）；上面的示例使用 `600`。 |
| `[daemon] retrain_interval_seconds` | 自动重新训练间隔；`604800` 为七天。 |
| `[daemon] print_windows`、`print_features`、`print_all_scores` | 在日志中额外输出窗口、特征和非异常分数。 |
| `[daemon] no_store` | 检测期间跳过特征窗口存储；告警仍会被存储。 |
| `[train] min_training_rows` | 最小模型拟合窗口数，不包括为参考基线保留的窗口。 |
| `[train] baseline_fraction` | 所选窗口中最早期用于固定基线的比例；默认 `0.2`，严格介于 0 和 1 之间。 |
| `[train] limit` | 最大选定的特征行数。当前选择按时间从最早到最新进行，因此该限制取最早的行。 |
| `[train] n_estimators` | 孤立森林树的数量；默认 `200`。更多树会增加训练工作量，但不保证更好的检测效果。 |
| `[train] random_state` | 用于可复现模型训练的随机种子；默认 `42`。 |
| `[train] threshold_percentile` | 用作 Guardd 告警截止值的低分位数；默认 `10.0`。**较低的值会产生更严格的截止值，通常会产生更少的告警。** |
| `[train] contamination` | 传递给孤立森林；默认 `0.01`。Guardd 使用原始分数及其自身的百分位截止值，因此这不会设置其告警率。 |
| `[gui] limit`、`[tui] limit` | 显示的最大匹配告警数；默认各为 `200`。 |
| `[logging] debug` | 在支持的地方启用调试日志记录；`--debug` 在 daemon 和 sensor 命令上显式启用它。 |