通过 GRPO 强化学习训练大语言模型，使其能够在真实 Kubernetes 集群中自主发现并修复 RBAC、Secrets、网络隔离、容器运行时和供应链等五大类的安全漏洞。
# K8sGuard
### **训练 LLM 以发现并修复 Kubernetes 安全漏洞。**
## 训练如何进行
```
┌─────────────────────────────────────────────┐
│ GRPO Training Loop │
│ (train.py) │
└────────────────────┬────────────────────────┘
│
┌──────────────────────────┼──────────────────────────┐
│ │ │
▼ ▼ ▼
┌───────────────────┐ ┌──────────────────────┐ ┌────────────────────┐
│ Agent LLM │ │ K8sGuard Env │ │ Security Judge │
│ (Qwen3-8B+LoRA) │ │ (OpenEnv server) │ │ (heuristic+LLM) │
│ │ │ │ │ │
│ vLLM generation │ │ Scenario injection │ │ Score actions: │
│ kubectl commands │ │ Command execution │ │ +0.5 to +1.0 ✓ │
│ finding: reports │ │ State tracking │ │ -0.5 to -1.0 ✗ │
│ remediate: fixes │ │ Episode management │ │ Feedback hints │
└────────┬──────────┘ └──────────┬───────────┘ └─────────┬──────────┘
│ │ │
│ ┌─────────────────────┼──────────────────────┐ │
│ │ ▼ │ │
│ │ ┌────────────────────────────────┐ │ │
│ │ │ Live K8s Cluster │ │ │
│ │ │ (k3s / EKS / GKE) │ │ │
│ │ │ │ │ │
│ │ │ ┌──────────┐ ┌───────────┐ │ │ │
│ │ │ │Injected │ │ Real K8s │ │ │ │
│ │ │ │ Vulns │ │ API │ │ │ │
│ │ │ └──────────┘ └───────────┘ │ │ │
│ │ └────────────────────────────────┘ │ │
│ └───────────────────────────────────────────-┘ │
│ │
└──────────────────────┬──────────────────────────────┘
│
▼
┌─────────────────────────────┐
│ GRPO Policy Update │
│ │
│ Reward → Advantage → LoRA │
│ weight update (BF16) │
│ │
│ Checkpoints → outputs/ │
└─────────────────────────────┘
```
**每个训练回合：**
1. **重置** — 环境将漏洞（特权 pod、通配符 RBAC、暴露的 secret 等）注入到隔离的命名空间中
2. **展开** — Agent 生成 kubectl 命令，检查资源，报告发现的问题，提出修复建议
3. **评分** — SecurityJudge 评估每个动作（参见下方的[奖励信号](#reward-signal)）
4. **更新** — GRPO 计算多次展开的优势并更新 LoRA 权重
Agent 学习在五个安全域中系统性地进行扫描，识别真实的错误配置，并应用正确的修复——所有操作都在实时集群上进行。
### 训练结果
奖励曲线显示了一个 Qwen3-8B Agent 在 150 个 GRPO 回合中学习扫描 K8s 集群的过程。Agent 起初为负分（浪费步骤，遗漏漏洞），随着学习系统性的扫描模式，逐渐收敛到正奖励。在最后 30 个回合中，解决率达到 87%。
按难度层级细分的性能表现。Agent 很快掌握了单漏洞场景（Tier 1），然后逐步学会处理多漏洞和全光谱场景（Tiers 3-4）。
## 训练快速入门
### 前置条件
- Python 3.10+，具有 24GB+ VRAM 的 GPU（推荐 A100/H100）
- 访问 Kubernetes 集群的权限（k3s, kind, EKS, GKE）
- `kubectl` 已配置有效的 kubeconfig
### 安装
```
git clone https://github.com/krishpyishere/k8sguard.git
cd k8sguard
pip install -e ".[train]"
```
### 完整设置（从零开始 k3s）
```
bash deploy/setup.sh # Installs k3s, kubectl, Python deps, creates training namespace
```
### 训练 Agent（3 个终端）
```
# 终端 1：Judge 模型（对 agent 操作进行评分）
trl vllm-serve --model Qwen/Qwen3-14B --host 0.0.0.0 --port 8001
# 终端 2：K8sGuard 环境（注入漏洞，执行命令）
LLM_BACKEND=openai LLM_BASE_URL=http://localhost:8001/v1 \
python -m server.app --scan-mode training
# 终端 3：GRPO 训练（微调 agent）
python train.py \
--model-id Qwen/Qwen3-8B \
--vllm-mode colocate \
--max-steps 200 \
--dataset-size 50
```
训练器运行 GRPO 回合：Agent 扫描集群，裁判对每个动作进行评分，并更新 LoRA 权重。检查点保存到 `outputs/`。
## 使用已训练的 Agent
一旦训练完成，模型可以扫描真实的集群：
```
# 以 scan 模式启动环境（无注入，无 training scaffolding）
python -m server.app --scan-mode scan
```
```
from k8sguard import K8sGuardEnv, K8sGuardAction
with K8sGuardEnv(base_url="http://localhost:8000") as env:
result = env.reset()
print(result.observation.command_output)
# Investigate
result = env.step(K8sGuardAction(command="kubectl get pods -A"))
print(result.observation.command_output)
# Report a finding
result = env.step(K8sGuardAction(command="finding: CRITICAL - Wildcard ClusterRole grants full cluster access"))
print(result.reward, result.observation.hint)
# Remediate
result = env.step(K8sGuardAction(command="remediate: kubectl delete clusterrole overpermissive-role"))
print(result.observation.command_output)
```
## 安全课程
Agent 学习检测五个领域的漏洞：
### RBAC 与身份
- 通配符 ClusterRoles/Roles（`*` 动词或资源）
- 权限提升动词（`escalate`, `bind`, `impersonate`）
- 通过 ClusterRoles 获得的广泛 secrets 访问权限
- 默认服务账户 token 自动挂载
### Secrets 与敏感数据
- 作为环境变量暴露的 Secrets（在 `kubectl describe` 中可见）
- Pod 环境变量中硬编码的凭证
- 存储在 ConfigMaps 而非 Secrets 中的敏感数据
### 网络隔离
- 没有 NetworkPolicy 的命名空间（不受限制的横向移动）
- 缺少出口策略（不受限制的出站流量）
- 通过 NodePort/LoadBalancer 暴露的服务
### 容器运行时
- 特权容器（`privileged: true`）
- 主机 PID/Network namespace 共享
- HostPath 卷挂载（容器逃逸向量）
- 以 root（UID 0）运行的容器
- 可写的根文件系统
- 危险的 Linux capabilities（`SYS_ADMIN`, `NET_ADMIN`, `SYS_PTRACE`, `ALL`）
- 缺少安全上下文
### 供应链
- 未固定的镜像（`:latest` 或无标签）
- 未通过 digest 固定的镜像
- 缺少资源限制（DoS 风险）
## 训练场景
漏洞被注入到隔离的命名空间（`k8sguard-training`）中，具有分层难度：
| 层级 | 难度 | 示例 |
|------|-----------|---------|
| 1 | 0.1 - 0.3 | 单个特权容器，root UID pod，`:latest` 镜像 |
| 2 | 0.3 - 0.5 | 通配符 RBAC，env vars 中的 secrets，缺少网络策略，危险的 capabilities |
| 3 | 0.5 - 0.7 | 多个漏洞：特权 pod + 暴露的服务 + 无网络策略 |
| 4 | 0.7+ | 全光谱：hostPath 挂载 + 通配符 RBAC + secrets 暴露 + 主机 namespaces |
### 奖励信号
SecurityJudge 对常见模式使用快速启发式路径，对于复杂的评估则回退到 LLM 裁判：
| 分数 | 含义 |
|-------|---------|
| +0.5 to +1.0 | 正确识别了一个真实漏洞 |
| +0.1 to +0.4 | 有用的调查步骤 |
| 0.0 | 中性（有效但未推进扫描） |
| -0.1 to -0.3 | 浪费的步骤或重复的命令 |
| -0.5 to -1.0 | 可能破坏集群的错误修复 |
## 架构
```
K8sGuard/
├── train.py # GRPO training (TRL + vLLM + LoRA)
├── __init__.py # Package exports
├── client.py # OpenEnv WebSocket client
├── models.py # K8sGuardAction, Observation, SecurityFinding, VulnerabilityScenario
├── pyproject.toml # Package config & dependencies
├── Dockerfile # Container build
├── deploy/
│ ├── setup.sh # k3s + Python env setup
│ └── start.sh # Server launcher
└── server/
├── app.py # FastAPI server (OpenEnv endpoints + /healthz)
├── constants.py # Severity levels, scan categories, system namespaces
├── k8s_backend.py # K8s auth (kubeconfig/in-cluster/token) + command dispatch
├── k8s_commands.py # kubectl command handler (get/describe/logs/auth can-i/...)
├── llm_client.py # LLM client (OpenAI-compatible, Anthropic, HuggingFace)
├── scanners.py # Programmatic scanners (RBAC, secrets, network, runtime, supply chain)
├── vulnerability_injectors.py # 12 injectors for training scenarios
├── scenario_generator.py # Tiered scenario templates (single vuln → full spectrum)
├── judge.py # Heuristic + LLM scoring of agent actions
└── k8sguard_environment.py # OpenEnv Environment (reset/step loop, scan + training modes)
```
### 关键组件
**`train.py`** — GRPO 训练脚本。每个训练步骤针对环境运行一个完整的安全扫描回合，并更新 Agent 的 LoRA 权重。
**`k8s_commands.py`** — 针对 K8s API 执行 kubectl 风格的命令。支持：
- 资源：pods, deployments, services, secrets, configmaps, serviceaccounts, roles, clusterroles, rolebindings, clusterrolebindings, networkpolicies, endpoints, resourcequotas, nodes, events
- 动词：`get`, `describe`, `logs`, `top`, `delete`, `scale`, `set`, `patch`, `rollout`, `taint`, `auth can-i`
**`scanners.py`** — 五个类别的扫描器，以编程方式检查集群资源并返回 `SecurityFinding` 对象。可独立用于审计集群或验证 Agent 的发现。
**`vulnerability_injectors.py`** — 12 种注入类型，用于创建与上述安全课程相匹配的真实错误配置。
**`llm_client.py`** — 统一的 LLM 客户端，用于裁判（OpenAI 兼容/vLLM, Anthropic, 或 HuggingFace）。
## 配置
所有配置均通过环境变量进行：
| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `SCAN_MODE` | `training` | `training`（注入漏洞）或 `scan`（真实集群） |
| `LLM_BACKEND` | `openai` | `openai`, `anthropic`, 或 `hf` |
| `LLM_MODEL` | auto | 模型名称（例如 `claude-sonnet-4-20250514`） |
| `LLM_BASE_URL` | `http://localhost:8001/v1` | vLLM/OpenAI 兼容 endpoint |
| `LLM_API_KEY` | `local` | OpenAI 兼容后端的 API key |
| `ANTHROPIC_API_KEY` | — | 当 `LLM_BACKEND=anthropic` 时必需 |
| `HF_TOKEN` | — | 当 `LLM_BACKEND=hf` 时必需 |
| `SCAN_NAMESPACES` | all non-system | 逗号分隔的命名空间列表 |
| `TRAINING_NAMESPACE` | `k8sguard-training` | 用于注入漏洞的命名空间 |
| `DIFFICULTY` | `0.3` | 训练模式下的场景难度（0.0-1.0） |
| `SCAN_CATEGORY` | all | 关注点：`rbac`, `secrets`, `network`, `runtime`, `supply_chain` |
| `MAX_STEPS` | `25` | 每回合最大 Agent 动作数 |
| `SCAN_LOG` | `scan_transcripts.jsonl` | 回合记录的路径 |
## 许可证
MIT