Debasish-87/kubertsec
GitHub: Debasish-87/kubertsec
基于eBPF的Kubernetes运行时安全平台，通过拦截系统调用实时检测并阻断反弹Shell、容器逃逸、权限提升等威胁。
Stars: 1 | Forks: 0
# KubeRTSec — Kubernetes 运行时安全
## 🎥 查看实际演示 (30 秒)
观看反向 shell 被实时检测并终止的过程。
```
┌─────────────────────────────────────────────────────────────────┐
│ Every Node │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ KubeRTSec Agent (DaemonSet) │ │
│ │ ┌────────────────────┐ ┌──────────────────────────┐ │ │
│ │ │ eBPF (execve │ │ Rules Engine │ │ │
│ │ │ tracepoint) │──▶│ (YAML hot-reload) │ │ │
│ │ └────────────────────┘ └────────────┬─────────────┘ │ │
│ │ │ POST /event │ │
│ └────────────────────────────────────────┼─────────────────┘ │
│ ▼ │
│ ┌───────────────────────────────────────────────────────────┐ │
│ │ KubeRTSec Controller (Deployment) │ │
│ │ REST API · WebSocket · BoltDB store · Prometheus metrics │ │
│ └────────────────────────┬──────────────────────────────────┘ │
│ │ nginx reverse proxy │
│ ┌────────────────────────▼──────────────────────────────────┐ │
│ │ KubeRTSec Dashboard (React 19 + recharts) │ │
│ │ Overview · Live Alerts · Pod Security · Metrics │ │
│ │ Attack Timeline · Detection Rules │ │
│ └───────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
```
| 组件 | 角色 |
|-----------|------|
| **Agent** | 每个节点上的 DaemonSet；将 eBPF tracepoint 挂载到 `execve`；评估规则；发送事件 |
| **Controller** | 中央 REST + WebSocket 服务器；在 BoltDB 中持久化告警；暴露 Prometheus 指标 |
| **Dashboard** | 通过 nginx 提供服务的 React 19 SPA；无直接内核或 K8s API 访问权限 |
## 🔍 系统组件
### Agent (eBPF Runtime)
### Controller
## 功能特性
- 🔍 **通过 eBPF 实现内核级可见性** —— 无需 sidecar、无需 ptrace、无需修改应用
- ⚡ **亚毫秒级检测** —— 在 Agent 内部进行规则评估，无需网络往返
- 🔥 **可热重载的 YAML 规则** —— 无需重启 agent 即可更新检测逻辑
- 🛡️ **三种响应模式** —— `detect`（检测）、`alert`（告警）、`enforce`（执行 SIGKILL）
- 🌐 **实时 WebSocket 流** —— 用于实时告警消费
- 📊 **Prometheus 指标** —— 支持可选的 Grafana Dashboard
- 🔐 **多事件关联** —— 用于检测链式攻击
- 🗂️ **Namespace 范围规则** —— 包含或排除特定的 Namespace
- 🧪 **内置攻击模拟** —— 无需真实攻击者即可测试规则
## 前置条件
| 需求 | 版本 | 备注 |
|-------------|---------|-------|
| Go | 1.21+ | Agent + Controller |
| Node.js | 20 LTS | 前端 |
| Docker + Compose | v2+ | Docker Compose 模式 |
| Linux kernel | 5.8+ | eBPF agent (需要 CO-RE / BTF) |
| kubectl | 1.26+ | Kubernetes 部署 |
| Root / `CAP_BPF` | — | 仅 Agent 需要 |
## ⚡ 实时告警
## 快速开始
### 选项 A — Docker Compose (推荐)
```
git clone https://github.com/Debasish-87/kubertsec.git
cd kubertsec
# 复制默认环境变量
cp .env.example .env
# 启动 controller + frontend (主机无需 eBPF)
make dev
```
| 服务 | URL |
|---------|-----|
| Dashboard | http://localhost:3000 |
| Controller API | http://localhost:8080 |
| Prometheus | http://localhost:9090 *(可选)* |
| Grafana | http://localhost:3001 *(可选)* |
**包含完整可观测性堆栈：**
```
docker compose --profile monitoring up --build
```
### 选项 B — 原生开发 (3 个终端)
**终端 1 — Controller:**
```
make controller
# 或手动：
cd backend
STORE_PATH=/tmp/kubertsec-dev.db \
RULES_PATH=configs/rules/process_rules.yaml \
PROMETHEUS_URL=http://localhost:9090 \
go run ./cmd/controller
```
**终端 2 — eBPF Agent** *(仅限 Linux，需要 root 权限):*
```
make agent
# 或手动：
cd backend
sudo -E RESPONSE_MODE=alert \
KUBESHIELD_CONTROLLER=http://localhost:8080/event \
go run ./cmd/agent
```
**终端 3 — Dashboard:**
```
make frontend
# 或手动：
cd frontend
cp .env.example .env.local
npm install
npm start
# 打开 http://localhost:3000
```
## 配置
### 后端 (controller + agent)
复制 `backend/env.example` → `backend/.env` 并根据需要编辑：
| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `LISTEN_ADDR` | `:8080` | Controller 监听地址 |
| `STORE_PATH` | `/tmp/kubertsec-dev.db` | BoltDB 告警存储路径 |
| `RULES_PATH` | `configs/rules/process_rules.yaml` | 检测规则文件 |
| `ALLOWLIST_PATH` | `configs/allowlist.yaml` | 进程白名单 |
| `RESPONSE_MODE` | `alert` | `detect` / `alert` / `enforce` |
| `KUBESHIELD_CONTROLLER` | `http://localhost:8080/event` | Agent → Controller 端点 |
| `PROMETHEUS_URL` | `http://localhost:9090` | Prometheus 抓取目标 |
| `GRAFANA_URL` | `http://localhost:3001` | Grafana 基础 URL |
| `GRAFANA_USER` | `admin` | Grafana 用户名 |
| `GRAFANA_PASSWORD` | `admin123` | Grafana 密码 (**生产环境请修改**) |
| `GRAFANA_TOKEN` | *(空)* | 服务账户 Token (Grafana 10+, 可选) |
### 前端
复制 `frontend/.env.example` → `frontend/.env.local`:
| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `REACT_APP_API_URL` | `http://localhost:8080` | Controller URL (构建时) |
| `REACT_APP_WS_URL` | `ws://localhost:8080/ws` | WebSocket URL (如果未设置则自动派生) |
| `REACT_APP_STATS_INTERVAL` | `30000` | 统计轮询间隔 (毫秒) |
| `REACT_APP_POD_INTERVAL` | `15000` | Pod 同步间隔 (毫秒) |
| `REACT_APP_MAX_ALERTS` | `500` | UI 内存中保留的最大告警数 |
## 检测规则
规则位于 `backend/configs/rules/process_rules.yaml`。
### 规则 Schema
```
rules:
- name: reverse_shell_nc # Unique name (used as alert rule_name)
severity: critical # critical | high | medium | low
mode: enforce # detect | alert | enforce
process_regex: "^nc$|^ncat$" # Regex matched against process name
args_any: # Alert if ANY of these appear in args
- "-e /bin/bash"
- "-e /bin/sh"
message: "Reverse shell detected (netcat)"
tags: [reverse_shell]
namespaces: # Restrict to specific namespaces (optional)
- production
exclude_namespaces: # Ignore these namespaces (optional)
- kube-system
```
**内置示例规则涵盖：**
- 反向 shell (`nc`, `ncat`, `bash -i`, `python -c`)
- 加密货币挖矿程序 (`xmrig`, `minergate`, `ethminer`)
- 容器逃逸 (`nsenter`, `unshare`, `chroot`)
- 权限提升 (`sudo`, `su`, SUID 二进制文件)
### 规则 UI
### 响应模式
| 模式 | 行为 |
|------|-----------|
| `detect` | 仅记录日志 —— 无网络调用，不终止进程 |
| `alert` | 记录日志 + 向 controller POST 事件 |
| `enforce` | 记录日志 + POST 事件 + 向违规进程发送 `SIGKILL` |
### 热重载规则
可以通过以下任一方式重载规则，而无需重启 agent：
1. **文件监视器** —— agent 每 30 秒轮询一次 `RULES_PATH`
2. **API** — `POST /api/v1/rules/reload`
3. **Dashboard** — 规则页面 → **↺ Reload Rules** 按钮
## API 参考
所有端点均由 controller 在 `:8080` 端口提供服务。
### 告警
| 方法 | 路径 | 描述 |
|--------|------|-------------|
| `GET` | `/api/v1/alerts` | 列出告警 (支持过滤 + 分页) |
| `GET` | `/api/v1/alerts/stats` | 按严重程度聚合统计 |
| `GET` | `/api/v1/alerts/:id` | 按 ID 获取单个告警 |
| `PUT` | `/api/v1/alerts/:id/ack` | 确认告警 |
| `DELETE` | `/api/v1/alerts/:id` | 删除告警 |
**`GET /api/v1/alerts` 的查询参数：**
`limit`, `offset`, `severity`, `namespace`, `pod`, `rule_name`, `process`, `since` (RFC3339), `until`, `acknowledged`
**示例：**
```
curl "http://localhost:8080/api/v1/alerts?severity=critical&limit=20&since=2026-01-01T00:00:00Z"
```
### 规则
| 方法 | 路径 | 描述 |
|--------|------|-------------|
| `GET` | `/api/v1/rules` | 列出所有活动规则 |
| `POST` | `/api/v1/rules` | 添加规则 (仅保存在内存中，不持久化到磁盘) |
| `POST` | `/api/v1/rules/reload` | 从磁盘热重载规则 |
| `GET` | `/api/v1/rules/:name` | 按名称获取规则 |
| `DELETE` | `/api/v1/rules/:name` | 将规则加入删除队列 |
### 其他端点
| 方法 | 路径 | 描述 |
|--------|------|-------------|
| `GET` | `/api/v1/pods` | 列出受监控的 Pod |
| `GET` | `/api/v1/posture` | 最新安全态势报告 |
| `GET` | `/api/v1/status` | Controller 健康状况 + 统计信息 |
| `GET` | `/api/v1/metrics/cluster` | 基于 Prometheus 的集群指标 |
| `GET` | `/ws` | WebSocket 事件流 |
| `POST` | `/event` | Agent 事件摄入端点 |
| `GET` | `/healthz` | 存活探针 |
| `GET` | `/metrics` | Prometheus 抓取目标 |
### WebSocket 协议
连接到 `ws:///ws`。
**连接时** —— 服务器发送最近的告警历史：
```
{ "type": "init", "data": [, ...] }
```
**当新的检测事件发生时：**
```
{ "type": "alert", "data": }
```
**告警对象字段：** `id`, `timestamp`, `rule_name`, `severity`, `namespace`, `pod`, `process`, `args`, `message`, `tags`, `acknowledged`
## Kubernetes 部署
```
# 1. 修改镜像 registry、secrets 和资源限制
vim deploy/kubernetes/kubertsec.yaml
# 2. Apply manifests
kubectl apply -f deploy/kubernetes/kubertsec.yaml
# 3. 验证 rollout
kubectl rollout status deployment/kubertsec-controller -n kubertsec
kubectl rollout status deployment/kubertsec-frontend -n kubertsec
kubectl rollout status daemonset/kubertsec-agent -n kubertsec
# 4. Port-forward dashboard (直到配置 Ingress)
kubectl port-forward svc/kubertsec-frontend -n kubertsec 3000:80
# 打开 http://localhost:3000
```
清单包含：
- `Namespace: kubertsec`
- Agent 的 `DaemonSet` (特权模式, `hostPID: true`)
- Controller 的 `Deployment` (非 root UID 1000, 只读根文件系统)
- Frontend 的 `Deployment` (nginx, 仅静态文件)
- `NetworkPolicy` 以限制组件间流量
- 用于 K8s Pod 元数据访问的 `ServiceAccount` 和 `ClusterRole`
### 构建与推送镜像
```
# 构建所有镜像
make docker-build REGISTRY=your-registry.io/your-org
# Push 到 registry
make docker-push REGISTRY=your-registry.io/your-org
# 或从 GitHub Container Registry 拉取预构建镜像
docker pull ghcr.io/debasish-87/kubertsec-controller:latest
docker pull ghcr.io/debasish-87/kubertsec-frontend:latest
```
## 可观测性：Prometheus & Grafana
使用端口转发 (本地开发)：**
```
make pf-start # Start port-forwards
# Prometheus → http://localhost:9090
# Grafana → http://localhost:3001
make pf-stop # Stop port-forwards
```
### 暴露的指标
抓取目标：`GET /metrics`
| 指标 | 类型 | 描述 |
|--------|------|-------------|
| `kubertsec_alerts_total` | Gauge | 总告警数，按 `severity` 标记 |
| `kubertsec_alerts_last_hour` | Gauge | 最近 60 分钟内的告警数 |
| `kubertsec_monitored_pods` | Gauge | Agent 当前可见的 Pod 数量 |
| `kubertsec_monitored_namespaces` | Gauge | 活跃 Namespace 数量 |
| `kubertsec_ws_clients` | Gauge | 活跃 WebSocket 连接数 |
| `kubertsec_uptime_seconds` | Counter | Controller 运行时间 (秒) |
预构建的 Grafana Dashboard JSON 位于 `monitoring/grafana/`。
### Grafana Dashboard
### 指标视图
## 攻击模拟
无需真实攻击者即可测试您的设置：
```
make attack-test
```
这将运行 `attack-test/attack-test.sh`，该脚本会：
1. 在测试 Pod 内部生成模拟攻击进程 (`curl`, `nc`, `xmrig`, `nsenter`, …)
2. 直接向 controller 发送合成事件
3. 触发每个内置检测规则
4. 报告哪些规则被触发以及严重程度
## 🧨 攻击期间会发生什么？
1. 恶意进程启动（例如，通过 nc 进行反向 shell）
2. eBPF agent 拦截 execve 系统调用
3. 规则引擎立即匹配模式
4. 生成告警并发送给 controller
5. (可选) 通过 SIGKILL 终止进程
6. Dashboard 实时更新
### 攻击时间线
### 检测结果
## 项目结构
```
kubertsec/
├── backend/
│ ├── bpf/ # eBPF C programs (CO-RE / BTF)
│ ├── cmd/
│ │ ├── agent/ # eBPF agent binary entrypoint
│ │ └── controller/ # REST + WebSocket server entrypoint
│ ├── pkg/
│ │ ├── correlation/ # Multi-event attack correlation
│ │ ├── ebpf/ # eBPF loader + ring-buffer event queue
│ │ ├── monitoring/ # Prometheus + Grafana API clients
│ │ ├── posture/ # K8s security posture assessment
│ │ ├── response/ # Process kill + allowlist enforcement
│ │ ├── rules/ # YAML rule engine + file watcher
│ │ ├── runtime/ # Container + process lineage tracking
│ │ └── store/ # BoltDB alert persistence
│ └── configs/
│ ├── rules/process_rules.yaml
│ └── allowlist.yaml
├── frontend/
│ └── src/
│ ├── config/ # Environment-aware configuration
│ ├── services/ # api.js · websocket.js
│ ├── store/ # AppStore.js (useReducer)
│ ├── hooks/ # useAPI · usePolling · useAction
│ ├── components/ # UI.jsx · Toast.jsx
│ └── pages/ # Overview · Alerts · Pods · Metrics
│ # Timeline · Rules
├── deploy/
│ └── kubernetes/kubertsec.yaml # Production K8s manifests
├── monitoring/
│ ├── prometheus.yml
│ └── grafana/ # Dashboard JSON + datasource config
├── attack-test/
│ └── attack-test.sh
├── docker-compose.yml # Production stack
├── docker-compose.override.yml # Hot-reload dev overrides
├── Makefile
├── .env.example
└── detection_rule.yml # Example rule for CI validation
```
## 开发
### 运行测试
```
make test # Go unit tests with race detector enabled
make vet # go vet static analysis
make fmt # gofmt formatting check
make lint # golangci-lint (requires local install)
```
### Makefile 目标
| 目标 | 描述 |
|--------|-------------|
| `make dev` | 通过 Docker Compose 启动 controller + frontend |
| `make controller` | 本地运行 controller |
| `make agent` | 本地运行 eBPF agent (Linux + root) |
| `make frontend` | 运行 React 开发服务器 |
| `make test` | 运行所有 Go 测试 |
| `make docker-build` | 构建所有 Docker 镜像 |
| `make docker-push` | 将镜像推送到镜像仓库 |
| `make attack-test` | 运行攻击模拟 |
| `make pf-start` | 启动 Prometheus/Grafana 端口转发 |
| `make pf-stop` | 停止端口转发 |
### 添加新的检测规则
1. 编辑 `backend/configs/rules/process_rules.yaml`
2. 遵循 [规则 Schema](#rule-schema)
3. 通过 `POST /api/v1/rules/reload` 热重载，或运行 `make attack-test` 进行验证
4. 提交包含规则和 `attack-test/` 中测试用例的 PR
## 安全注意事项
| 主题 | 详情 |
|-------|--------|
| **Agent 权限** | Agent 需要 `privileged: true` 和 `hostPID: true` —— 这是 eBPF 内核追踪的固有限制。在生产部署前请仔细审查 DaemonSet 清单。 |
| **Controller** | 以非 root (UID 1000) 身份运行，具有只读根文件系统。 |
| **Frontend** | 仅提供静态文件并代理到 controller —— 无直接内核或 K8s API 访问权限。 |
| **Grafana 密码** | 在任何生产部署之前更改 `GRAFANA_PASSWORD`。 |
| **TLS** | 在生产环境中通过 Ingress + cert-manager 启用 TLS。清单中包含示例注释。 |
| **NetworkPolicy** | 包含在清单中。请确保您的 CNI 插件强制执行它。 |
| **Secrets** | 不要提交 `.env` 文件。使用 Kubernetes Secrets 或 Secrets 管理器 (Vault, AWS Secrets Manager)。 |
| **白名单** | 使用 `configs/allowlist.yaml` 抑制已知良好的进程并减少告警噪音。 |
如需报告安全漏洞，请参阅 [SECURITY.md](SECURITY.md)。**请勿公开提出 Issue。**
## 贡献
我们欢迎各种形式的贡献 —— 新的检测规则、后端功能、UI 改进、文档和错误报告。
1. Fork 本仓库并创建一个功能分支：`feat/your-feature`
2. 提交前必须通过 `make test`
3. 向 `main` 分支提交 Pull Request —— 描述您的 PR 增加了什么规则、检测或 UI 更改
4. 引用任何相关的 Issues
完整指南请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。
## 📊 项目状态
- 早期阶段 (v0.1.0)
- 积极开发中
- 寻找贡献者
## 行为准则
本项目遵守 Contributor Covenant。详情请参阅 [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)。
## 许可证
[MIT](LICENSE) © 2026 Debasish Mohanty 及贡献者
基于 eBPF 的 Kubernetes 运行时威胁检测 —— 实时捕获反向 shell、加密货币挖矿程序、容器逃逸和权限提升。
## 🚀 Dashboard 预览
## 🎥 查看实际演示 (30 秒)
观看反向 shell 被实时检测并终止的过程。
观看 KubeRTSec 如何实时检测并阻止实时攻击。
```
┌─────────────────────────────────────────────────────────────────┐
│ Every Node │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ KubeRTSec Agent (DaemonSet) │ │
│ │ ┌────────────────────┐ ┌──────────────────────────┐ │ │
│ │ │ eBPF (execve │ │ Rules Engine │ │ │
│ │ │ tracepoint) │──▶│ (YAML hot-reload) │ │ │
│ │ └────────────────────┘ └────────────┬─────────────┘ │ │
│ │ │ POST /event │ │
│ └────────────────────────────────────────┼─────────────────┘ │
│ ▼ │
│ ┌───────────────────────────────────────────────────────────┐ │
│ │ KubeRTSec Controller (Deployment) │ │
│ │ REST API · WebSocket · BoltDB store · Prometheus metrics │ │
│ └────────────────────────┬──────────────────────────────────┘ │
│ │ nginx reverse proxy │
│ ┌────────────────────────▼──────────────────────────────────┐ │
│ │ KubeRTSec Dashboard (React 19 + recharts) │ │
│ │ Overview · Live Alerts · Pod Security · Metrics │ │
│ │ Attack Timeline · Detection Rules │ │
│ └───────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
```
| 组件 | 角色 |
|-----------|------|
| **Agent** | 每个节点上的 DaemonSet；将 eBPF tracepoint 挂载到 `execve`；评估规则；发送事件 |
| **Controller** | 中央 REST + WebSocket 服务器；在 BoltDB 中持久化告警；暴露 Prometheus 指标 |
| **Dashboard** | 通过 nginx 提供服务的 React 19 SPA；无直接内核或 K8s API 访问权限 |
## 🔍 系统组件
### Agent (eBPF Runtime)
### Controller
## 功能特性
- 🔍 **通过 eBPF 实现内核级可见性** —— 无需 sidecar、无需 ptrace、无需修改应用
- ⚡ **亚毫秒级检测** —— 在 Agent 内部进行规则评估，无需网络往返
- 🔥 **可热重载的 YAML 规则** —— 无需重启 agent 即可更新检测逻辑
- 🛡️ **三种响应模式** —— `detect`（检测）、`alert`（告警）、`enforce`（执行 SIGKILL）
- 🌐 **实时 WebSocket 流** —— 用于实时告警消费
- 📊 **Prometheus 指标** —— 支持可选的 Grafana Dashboard
- 🔐 **多事件关联** —— 用于检测链式攻击
- 🗂️ **Namespace 范围规则** —— 包含或排除特定的 Namespace
- 🧪 **内置攻击模拟** —— 无需真实攻击者即可测试规则
## 前置条件
| 需求 | 版本 | 备注 |
|-------------|---------|-------|
| Go | 1.21+ | Agent + Controller |
| Node.js | 20 LTS | 前端 |
| Docker + Compose | v2+ | Docker Compose 模式 |
| Linux kernel | 5.8+ | eBPF agent (需要 CO-RE / BTF) |
| kubectl | 1.26+ | Kubernetes 部署 |
| Root / `CAP_BPF` | — | 仅 Agent 需要 |
## ⚡ 实时告警
## 快速开始
### 选项 A — Docker Compose (推荐)
```
git clone https://github.com/Debasish-87/kubertsec.git
cd kubertsec
# 复制默认环境变量
cp .env.example .env
# 启动 controller + frontend (主机无需 eBPF)
make dev
```
| 服务 | URL |
|---------|-----|
| Dashboard | http://localhost:3000 |
| Controller API | http://localhost:8080 |
| Prometheus | http://localhost:9090 *(可选)* |
| Grafana | http://localhost:3001 *(可选)* |
**包含完整可观测性堆栈：**
```
docker compose --profile monitoring up --build
```
### 选项 B — 原生开发 (3 个终端)
**终端 1 — Controller:**
```
make controller
# 或手动：
cd backend
STORE_PATH=/tmp/kubertsec-dev.db \
RULES_PATH=configs/rules/process_rules.yaml \
PROMETHEUS_URL=http://localhost:9090 \
go run ./cmd/controller
```
**终端 2 — eBPF Agent** *(仅限 Linux，需要 root 权限):*
```
make agent
# 或手动：
cd backend
sudo -E RESPONSE_MODE=alert \
KUBESHIELD_CONTROLLER=http://localhost:8080/event \
go run ./cmd/agent
```
**终端 3 — Dashboard:**
```
make frontend
# 或手动：
cd frontend
cp .env.example .env.local
npm install
npm start
# 打开 http://localhost:3000
```
## 配置
### 后端 (controller + agent)
复制 `backend/env.example` → `backend/.env` 并根据需要编辑：
| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `LISTEN_ADDR` | `:8080` | Controller 监听地址 |
| `STORE_PATH` | `/tmp/kubertsec-dev.db` | BoltDB 告警存储路径 |
| `RULES_PATH` | `configs/rules/process_rules.yaml` | 检测规则文件 |
| `ALLOWLIST_PATH` | `configs/allowlist.yaml` | 进程白名单 |
| `RESPONSE_MODE` | `alert` | `detect` / `alert` / `enforce` |
| `KUBESHIELD_CONTROLLER` | `http://localhost:8080/event` | Agent → Controller 端点 |
| `PROMETHEUS_URL` | `http://localhost:9090` | Prometheus 抓取目标 |
| `GRAFANA_URL` | `http://localhost:3001` | Grafana 基础 URL |
| `GRAFANA_USER` | `admin` | Grafana 用户名 |
| `GRAFANA_PASSWORD` | `admin123` | Grafana 密码 (**生产环境请修改**) |
| `GRAFANA_TOKEN` | *(空)* | 服务账户 Token (Grafana 10+, 可选) |
### 前端
复制 `frontend/.env.example` → `frontend/.env.local`:
| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `REACT_APP_API_URL` | `http://localhost:8080` | Controller URL (构建时) |
| `REACT_APP_WS_URL` | `ws://localhost:8080/ws` | WebSocket URL (如果未设置则自动派生) |
| `REACT_APP_STATS_INTERVAL` | `30000` | 统计轮询间隔 (毫秒) |
| `REACT_APP_POD_INTERVAL` | `15000` | Pod 同步间隔 (毫秒) |
| `REACT_APP_MAX_ALERTS` | `500` | UI 内存中保留的最大告警数 |
## 检测规则
规则位于 `backend/configs/rules/process_rules.yaml`。
### 规则 Schema
```
rules:
- name: reverse_shell_nc # Unique name (used as alert rule_name)
severity: critical # critical | high | medium | low
mode: enforce # detect | alert | enforce
process_regex: "^nc$|^ncat$" # Regex matched against process name
args_any: # Alert if ANY of these appear in args
- "-e /bin/bash"
- "-e /bin/sh"
message: "Reverse shell detected (netcat)"
tags: [reverse_shell]
namespaces: # Restrict to specific namespaces (optional)
- production
exclude_namespaces: # Ignore these namespaces (optional)
- kube-system
```
**内置示例规则涵盖：**
- 反向 shell (`nc`, `ncat`, `bash -i`, `python -c`)
- 加密货币挖矿程序 (`xmrig`, `minergate`, `ethminer`)
- 容器逃逸 (`nsenter`, `unshare`, `chroot`)
- 权限提升 (`sudo`, `su`, SUID 二进制文件)
### 规则 UI
### 响应模式
| 模式 | 行为 |
|------|-----------|
| `detect` | 仅记录日志 —— 无网络调用，不终止进程 |
| `alert` | 记录日志 + 向 controller POST 事件 |
| `enforce` | 记录日志 + POST 事件 + 向违规进程发送 `SIGKILL` |
### 热重载规则
可以通过以下任一方式重载规则，而无需重启 agent：
1. **文件监视器** —— agent 每 30 秒轮询一次 `RULES_PATH`
2. **API** — `POST /api/v1/rules/reload`
3. **Dashboard** — 规则页面 → **↺ Reload Rules** 按钮
## API 参考
所有端点均由 controller 在 `:8080` 端口提供服务。
### 告警
| 方法 | 路径 | 描述 |
|--------|------|-------------|
| `GET` | `/api/v1/alerts` | 列出告警 (支持过滤 + 分页) |
| `GET` | `/api/v1/alerts/stats` | 按严重程度聚合统计 |
| `GET` | `/api/v1/alerts/:id` | 按 ID 获取单个告警 |
| `PUT` | `/api/v1/alerts/:id/ack` | 确认告警 |
| `DELETE` | `/api/v1/alerts/:id` | 删除告警 |
**`GET /api/v1/alerts` 的查询参数：**
`limit`, `offset`, `severity`, `namespace`, `pod`, `rule_name`, `process`, `since` (RFC3339), `until`, `acknowledged`
**示例：**
```
curl "http://localhost:8080/api/v1/alerts?severity=critical&limit=20&since=2026-01-01T00:00:00Z"
```
### 规则
| 方法 | 路径 | 描述 |
|--------|------|-------------|
| `GET` | `/api/v1/rules` | 列出所有活动规则 |
| `POST` | `/api/v1/rules` | 添加规则 (仅保存在内存中，不持久化到磁盘) |
| `POST` | `/api/v1/rules/reload` | 从磁盘热重载规则 |
| `GET` | `/api/v1/rules/:name` | 按名称获取规则 |
| `DELETE` | `/api/v1/rules/:name` | 将规则加入删除队列 |
### 其他端点
| 方法 | 路径 | 描述 |
|--------|------|-------------|
| `GET` | `/api/v1/pods` | 列出受监控的 Pod |
| `GET` | `/api/v1/posture` | 最新安全态势报告 |
| `GET` | `/api/v1/status` | Controller 健康状况 + 统计信息 |
| `GET` | `/api/v1/metrics/cluster` | 基于 Prometheus 的集群指标 |
| `GET` | `/ws` | WebSocket 事件流 |
| `POST` | `/event` | Agent 事件摄入端点 |
| `GET` | `/healthz` | 存活探针 |
| `GET` | `/metrics` | Prometheus 抓取目标 |
### WebSocket 协议
连接到 `ws://
### 指标视图
## 攻击模拟
无需真实攻击者即可测试您的设置：
```
make attack-test
```
这将运行 `attack-test/attack-test.sh`，该脚本会：
1. 在测试 Pod 内部生成模拟攻击进程 (`curl`, `nc`, `xmrig`, `nsenter`, …)
2. 直接向 controller 发送合成事件
3. 触发每个内置检测规则
4. 报告哪些规则被触发以及严重程度
## 🧨 攻击期间会发生什么？
1. 恶意进程启动（例如，通过 nc 进行反向 shell）
2. eBPF agent 拦截 execve 系统调用
3. 规则引擎立即匹配模式
4. 生成告警并发送给 controller
5. (可选) 通过 SIGKILL 终止进程
6. Dashboard 实时更新
### 攻击时间线
### 检测结果
## 项目结构
```
kubertsec/
├── backend/
│ ├── bpf/ # eBPF C programs (CO-RE / BTF)
│ ├── cmd/
│ │ ├── agent/ # eBPF agent binary entrypoint
│ │ └── controller/ # REST + WebSocket server entrypoint
│ ├── pkg/
│ │ ├── correlation/ # Multi-event attack correlation
│ │ ├── ebpf/ # eBPF loader + ring-buffer event queue
│ │ ├── monitoring/ # Prometheus + Grafana API clients
│ │ ├── posture/ # K8s security posture assessment
│ │ ├── response/ # Process kill + allowlist enforcement
│ │ ├── rules/ # YAML rule engine + file watcher
│ │ ├── runtime/ # Container + process lineage tracking
│ │ └── store/ # BoltDB alert persistence
│ └── configs/
│ ├── rules/process_rules.yaml
│ └── allowlist.yaml
├── frontend/
│ └── src/
│ ├── config/ # Environment-aware configuration
│ ├── services/ # api.js · websocket.js
│ ├── store/ # AppStore.js (useReducer)
│ ├── hooks/ # useAPI · usePolling · useAction
│ ├── components/ # UI.jsx · Toast.jsx
│ └── pages/ # Overview · Alerts · Pods · Metrics
│ # Timeline · Rules
├── deploy/
│ └── kubernetes/kubertsec.yaml # Production K8s manifests
├── monitoring/
│ ├── prometheus.yml
│ └── grafana/ # Dashboard JSON + datasource config
├── attack-test/
│ └── attack-test.sh
├── docker-compose.yml # Production stack
├── docker-compose.override.yml # Hot-reload dev overrides
├── Makefile
├── .env.example
└── detection_rule.yml # Example rule for CI validation
```
## 开发
### 运行测试
```
make test # Go unit tests with race detector enabled
make vet # go vet static analysis
make fmt # gofmt formatting check
make lint # golangci-lint (requires local install)
```
### Makefile 目标
| 目标 | 描述 |
|--------|-------------|
| `make dev` | 通过 Docker Compose 启动 controller + frontend |
| `make controller` | 本地运行 controller |
| `make agent` | 本地运行 eBPF agent (Linux + root) |
| `make frontend` | 运行 React 开发服务器 |
| `make test` | 运行所有 Go 测试 |
| `make docker-build` | 构建所有 Docker 镜像 |
| `make docker-push` | 将镜像推送到镜像仓库 |
| `make attack-test` | 运行攻击模拟 |
| `make pf-start` | 启动 Prometheus/Grafana 端口转发 |
| `make pf-stop` | 停止端口转发 |
### 添加新的检测规则
1. 编辑 `backend/configs/rules/process_rules.yaml`
2. 遵循 [规则 Schema](#rule-schema)
3. 通过 `POST /api/v1/rules/reload` 热重载，或运行 `make attack-test` 进行验证
4. 提交包含规则和 `attack-test/` 中测试用例的 PR
## 安全注意事项
| 主题 | 详情 |
|-------|--------|
| **Agent 权限** | Agent 需要 `privileged: true` 和 `hostPID: true` —— 这是 eBPF 内核追踪的固有限制。在生产部署前请仔细审查 DaemonSet 清单。 |
| **Controller** | 以非 root (UID 1000) 身份运行，具有只读根文件系统。 |
| **Frontend** | 仅提供静态文件并代理到 controller —— 无直接内核或 K8s API 访问权限。 |
| **Grafana 密码** | 在任何生产部署之前更改 `GRAFANA_PASSWORD`。 |
| **TLS** | 在生产环境中通过 Ingress + cert-manager 启用 TLS。清单中包含示例注释。 |
| **NetworkPolicy** | 包含在清单中。请确保您的 CNI 插件强制执行它。 |
| **Secrets** | 不要提交 `.env` 文件。使用 Kubernetes Secrets 或 Secrets 管理器 (Vault, AWS Secrets Manager)。 |
| **白名单** | 使用 `configs/allowlist.yaml` 抑制已知良好的进程并减少告警噪音。 |
如需报告安全漏洞，请参阅 [SECURITY.md](SECURITY.md)。**请勿公开提出 Issue。**
## 贡献
我们欢迎各种形式的贡献 —— 新的检测规则、后端功能、UI 改进、文档和错误报告。
1. Fork 本仓库并创建一个功能分支：`feat/your-feature`
2. 提交前必须通过 `make test`
3. 向 `main` 分支提交 Pull Request —— 描述您的 PR 增加了什么规则、检测或 UI 更改
4. 引用任何相关的 Issues
完整指南请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。
## 📊 项目状态
- 早期阶段 (v0.1.0)
- 积极开发中
- 寻找贡献者
## 行为准则
本项目遵守 Contributor Covenant。详情请参阅 [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)。
## 许可证
[MIT](LICENSE) © 2026 Debasish Mohanty 及贡献者标签：AMSI绕过, CSV导出, Docker镜像, Go语言, JSONLines, Kubernetes 安全, Linux 内核, PB级数据处理, React, Syscalls, Web截图, Web报告查看器, 协议分析, 反向Shell检测, 响应阻断, 威胁检测, 子域名突变, 安全仪表盘, 安全运维, 容器安全, 容器逃逸, 恶意软件防护, 挖矿病毒检测, 日志审计, 时间线生成, 权限提升, 模型鲁棒性, 程序破解, 系统调用拦截, 自定义脚本, 自定义请求头, 请求拦截, 零信任