KernelEye

面向 Linux 服务器的内核级流量智能与威胁修复。

KernelEye 是一个面向 Linux 服务器的自托管安全监控平台。它使用 Go 代理中的 eBPF、TC 和 XDP 来观察网络元数据、对可疑活动进行评分，并通过内核级 XDP 阻断和 ipset/iptables 规则实施修复。Go 后端存储并分析事件，而 React 仪表盘提供服务器管理、实时流量、威胁视图、已封禁 IP、白名单、报告和分析功能。

功能概述

• 基于 eBPF 的实时 Linux 流量监控。
• 基于 TC 钩子的带宽追踪。
• 通过 shared/scoring 中的共享 Go 评分逻辑进行威胁评分。
• 代理端分析及可选自动修复。
• XDP 快速路径数据包阻断及 ipset/iptables 备用。
• 后端分析工作器、封禁管理、数据保留及月度报表。
• 基于 gRPC 的事件采集和代理与后端之间的指令流（使用 TLS/mTLS 加密及 HMAC 指令签名）。
• 单调 nonce 重放防护及所有修复操作的结构化审计日志。
• 定期 eBPF 映射完整性验证及状态证明报告。
• 基于 React 的仪表盘，支持 WebSocket 更新、服务器详情视图、已封禁 IP 管理、白名单、报告及分析。
• 配置 MaxMind 数据库时的 GeoIP 增强。
• 支持 GitHub 和 Google 的 OAuth（单拥有者自托管访问）。
• 隐私优先：仅采集元数据，不采集数据包负载。

架构

受监控的 Linux 主机
  eBPF 流量探针 + TC 带宽钩子
  XDP 防火墙及 ipset/iptables 修复
  Go 代理（HMAC 指令验证、审计日志）
      |
      | gRPC（TLS/mTLS）+ HMAC 签名的封禁指令
      v
Go 后端 API
  Fiber HTTP API
  gRPC 采集/封禁服务（TLS/mTLS、指令签名）
  分析工作器、封禁管理器、数据保留、报表
  完整性报告处理器
      |
      v
PostgreSQL
      ^
      |
React 仪表盘
  REST API + WebSocket 实时更新

关键组件

代理

代理位于 agent/ 目录，是 Linux 主机进程。

• agent/main.go 启动注册、eBPF 加载、带宽追踪、修复、评分、聚合及封禁指令流。
• agent/ebpf/traffic_probe.c 捕获流量元数据。
• agent/ebpf/xdp_firewall.c 实现 XDP 数据包过滤。
• agent/tc.go 配置 TC 带宽追踪。
• agent/aggregator.go 将事件批量处理并刷新到后端。
• agent/history_store.go 和 agent/flush.go 处理本地持久化及重试行为。
• agent/remediation/ 包含分析器、自动封禁、XDP、ipset 及混合修复器。

代理需要 Linux 系统以及 eBPF/XDP 操作所需的高权限。

后端

后端位于 backend/ 目录。

• backend/cmd/api/main.go 启动 Fiber HTTP API 和 gRPC 服务。
• backend/internal/api/ 包含认证、仪表盘处理器、gRPC 处理器、封禁 API、白名单 API、WebSocket 处理及速率限制。
• backend/internal/analysis/ 包含评分工作器、封禁管理、数据保留及月度报表逻辑。
• backend/internal/database/ 包含 sqlc 生成的数据库访问代码。
• backend/internal/geoip/ 处理 GeoIP 增强。
• backend/internal/email/ 在配置后通过 Mailtrap 发送电子邮件。
• backend/migrations/ 包含 PostgreSQL 迁移文件。

HTTP 默认端口为 8080；gRPC 默认端口为 9091。

仪表盘

仪表盘位于 dashboard/ 目录，是一个 Vite React 应用。

• dashboard/src/pages/ 包含概览、服务器、服务器详情、威胁、告警、报表、可视化工具、已封禁 IP、白名单、登录、个人资料及 OAuth 回调页面。
• dashboard/src/components/ 包含实时流量、封禁动态、图表、服务器列表、配置器及共享布局组件。
• dashboard/src/api/client.ts 定义 REST API 客户端。
• dashboard/src/context/WebSocketContext.tsx 管理实时事件更新。

开发服务器配置为 http://localhost:3000。

着陆页

公开营销网站位于 kerneleye-landing-page/。生产环境的前端镜像会同时构建着陆页和仪表盘，然后通过 nginx 提供服务。

共享代码和协议

• shared/scoring/ 包含代理和后端共同使用的共享威胁评分模块。
• shared/cmdsigning/ 包含 HMAC-SHA256 指令签名和 nonce 重放防护模块。
• proto/kerneleye/v1/ 包含用于采集和封禁服务的 protobuf 定义。
• proto/gen/go/ 包含生成的 Go protobuf 代码。

隐私

KernelEye 不会检查数据包负载或应用内容。

采集的元数据包括：

• 源和目标 IP 地址。
• 端口和协议。
• TCP 标志和连接计数器。
• 数据包和字节数。
• 流量方向。
• 时间戳。
• 可选 GeoIP/ASN 增强。

不采集的内容：

• 数据包负载。
• HTTP 请求体或头部。
• 用户凭据。
• 应用数据。

威胁评分

威胁评分在 shared/scoring/scorer.go 中实现。当前的评分器比单一线性公式更精细：它考虑 SYN 速率、唯一端口访问、握手失败、突发行为、服务滥用、方向、置信度以及分数随时间衰减。

默认分类阈值：

< 20   正常
20-39  可疑
>= 40  恶意
>= 40  当启用修复时符合自动封禁条件

后端分析工作器还会使用累积流量窗口，并可为高风险源触发封禁管理。

修复

KernelEye 支持在代理上启用主动修复。

仪表盘还提供已封禁 IP 和白名单管理。

快速开始

前提条件

• Go 1.25.x（当前后端和代理模块）。
• Node.js/npm（用于 React 应用）。
• PostgreSQL 14+ 或 15+。
• 对于代理：支持 BTF 的 Linux 系统、root 权限、clang/LLVM、bpftool、libbpf 头文件、ipset 和 iptables。

配置环境

cp .env.example .env

至少设置：

DATABASE_URL=postgres://kerneleye:<password>@localhost:5432/kerneleye?sslmode=disable
JWT_SECRET=<至少32个字符>
API_KEY_SECRET=<强密码>
CORS_ORIGINS=http://localhost:3000

可选集成包括 Redis 速率限制、Mailtrap 电子邮件、GitHub/Google OAuth 和 MaxMind GeoIP。

启动后端

cd backend
go mod download
go run cmd/api/main.go

后端启动：

• HTTP API 位于 http://localhost:8080
• gRPC 位于 localhost:9091

启动仪表盘

cd dashboard
npm install
npm run dev

打开 http://localhost:3000。

登录仅支持 OAuth。设置 AUTH_OWNER_EMAIL 并至少配置一个 OAuth 提供商（GitHub 或 Google）以访问仪表盘。只有配置的拥有者邮箱才允许登录。

构建并运行代理

cd agent
bpftool btf dump file /sys/kernel/btf/vmlinux format c > ebpf/vmlinux.h
go generate ./...
go build -o kerneleye-agent
sudo KERNELEYE_API_KEY=<server-api-key> \
  KERNELEYE_SERVER=localhost:8080 \
  KERNELEYE_GRPC_URL=localhost:9091 \
  ./kerneleye-agent

有用的代理标志：

-enable-remediation     启用主动封禁和自动封禁
-xdp                    启用 XDP 快速路径封禁
-interface <name>       选择 XDP 网络接口
--read-only             仅监控和报告，不进行封禁
--insecure              禁用 TLS（仅开发环境）
--tls-ca-file <path>    用于 TLS 验证的后端 CA 证书
--tls-cert-file <path>  用于 mTLS 的代理客户端证书
--tls-key-file <path>   代理客户端私钥
-list-blocked           打印当前 ipset 状态并退出
-flush-blocklists       清空 ipset 和 XDP 封禁列表并退出
-clear-data             移除本地代理 SQLite 存储并退出
-version                打印构建版本

当设置了 --enable-remediation 时，代理和后端都必须配置 CMD_SIGNING_KEY。使用 openssl rand -base64 32 生成。

项目结构

kerneleye/
├── agent/                     Go eBPF/XDP 监控代理
│   ├── ebpf/                  eBPF C 程序和编译后的对象
│   ├── remediation/           分析器、XDP、ipset、混合修复
│   ├── assets/                嵌入式 XDP 对象资源
│   └── scripts/               ipset 辅助脚本和服务文件
├── backend/                   Go Fiber API 和 gRPC 后端
│   ├── cmd/api/               后端入口
│   ├── internal/api/          HTTP、认证、WebSocket、gRPC、封禁 API
│   ├── internal/analysis/     工作器、封禁、保留、报表
│   ├── internal/database/     sqlc 生成的查询和辅助函数
│   ├── internal/email/        Mailtrap 电子邮件服务
│   ├── internal/geoip/        MaxMind GeoIP 服务
│   └── migrations/            PostgreSQL 迁移
├── dashboard/                 React 仪表盘应用
├── kerneleye-landing-page/    React 着陆页应用
├── proto/                     protobuf 定义和生成的 Go 代码
├── shared/
│   ├── scoring/            共享威胁评分 Go 模块
│   └── cmdsigning/         HMAC 指令签名和 nonce 追踪
├── docs/                      附加项目文档
├── tests/                     流量模拟 shell 脚本
├── docker/                    前端 nginx 和安装脚本模板
├── Dockerfile.backend         后端容器构建
├── Dockerfile.frontend        着陆页 + 仪表盘 + 代理下载镜像
├── docker-compose.yml         生产导向的 Compose 堆栈
└── Makefile                   生成、构建和 Docker 目标

技术栈

已测试环境

KernelEye 代理已在以下配置上测试。随着新环境的验证，该表格会更新。

我们使用 ebpf-go 进行 eBPF 用户空间集成。

构建与生成

常用的 Make 目标：

make gen-proto
make gen-sql
make gen-ebpf
make build-backend
make build-agent
make build
make docker-build

前端 Docker 镜像会构建着陆页、仪表盘以及一个可下载的 Linux 代理二进制文件。

文档

• 入门指南
• 开发指南
• 代码库索引
• 安全架构
• 威胁模型
• 信任模型
• 评分系统分析
• 代理架构
• 修复
• 数据库迁移

联系方式

• 网站：https://example.com
• 邮箱：[email protected]

许可证

KernelEye 在 Apache License, Version 2.0（Apache-2.0）下开源。详见 LICENSE。

版权所有 2026 Abdeljalil Aitetaleb。

KernelEye 名称、徽标和视觉标识不在 Apache 许可证范围内。品牌使用条款请参见 TRADEMARKS.md。