mustafa0766/kubesentinel
GitHub: mustafa0766/kubesentinel
一款 Kubernetes 容器镜像安全扫描器，集成 Trivy、Syft 和 Cosign，提供漏洞检测、SBOM 生成、签名验证、安全评分和可视化报告。
Stars: 1 | Forks: 0
# KubeSentinel
**Kubernetes 容器镜像安全扫描器**
KubeSentinel 是一款 DevSecOps 工具，用于扫描您 Kubernetes 集群中运行的容器镜像，以发现漏洞、安全配置错误和合规性问题。它能生成具有可操作性的 HTML 仪表板、CSV 和 JSON 报告，非常适合安全团队使用。
```
kubesentinel scan --output reports/
```
## 功能
- **Kubernetes 镜像收集** — 从 Pod、Deployment、DaemonSet、StatefulSet、Job 和 CronJob 中发现镜像
- **漏洞扫描** — 集成 [Trivy](https://trivy.dev) 进行 CVE 检测
- **SBOM 生成** — 通过 [Syft](https://github.com/anchore/syft) 可选生成 CycloneDX SBOM
- **签名验证** — 通过 [Cosign](https://docs.sigstore.dev) 进行可选的镜像签名检查
- **安全评分** — 针对单个镜像和整个集群的安全评分（0–100）
- **最佳实践审计** — 检测 `latest` 标签、root 用户、特权容器、主机网络等
- **HTML 仪表板** — 包含 Chart.js 可视化图表的独立报告
- **并行扫描** — 由 Trivy 服务器模式支持的工作池，实现快速、缓存安全的并发扫描
## 架构
```
kubeconfig
│
▼
Kubernetes API
│
▼
Collect Images
│
▼
Unique Images
│
▼
┌───────────────┐
│ Worker Pool │
│ N Goroutines │
└───────────────┘
│
├── Trivy
├── Syft
├── Cosign
└── Security Context
│
▼
Image Analysis
│
▼
Risk Calculation
│
▼
HTML + CSV + JSON + SBOM
```
## 快速开始
### 前置条件
- Go 1.22+
- 可访问的 Kubernetes 集群（已配置 `kubectl`）
- [Trivy](https://trivy.dev/getting-started/installation/)（漏洞扫描必需）
- [Syft](https://github.com/anchore/syft#installation)（可选，用于 SBOM）
- [Cosign](https://docs.sigstore.dev/cosign/system_config/installation/)（可选，用于签名验证）
### 安装
```
git clone https://github.com/mustafa0766/kubesentinel.git
cd kubesentinel
make build
```
### 全局安装（可在任意位置运行）
```
# 选项 1：go install（将二进制文件放入 $GOPATH/bin，通常是 ~/go/bin）
go install ./cmd/kubesentinel
# 选项 2：将构建好的二进制文件复制到您的 PATH 中
make build
sudo cp bin/kubesentinel /usr/local/bin/
# 然后从任意目录运行：
kubesentinel scan --output ~/kubesentinel-reports/
```
如果 `~/go/bin` 不在您的 PATH 中，请将其添加到您的 shell 配置文件中：
```
echo 'export PATH="$HOME/go/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc
```
### 用法
```
# 带 HTML 仪表板的全面扫描
./bin/kubesentinel scan --output reports/
# 扫描特定 namespaces
./bin/kubesentinel scan -n production -n staging --output reports/
# 使用 16 个 worker 的并行扫描
./bin/kubesentinel scan --workers 16 --output reports/
# 包含 SBOM 和 Cosign 验证
./bin/kubesentinel scan --sbom --cosign --output reports/
# 仅收集镜像（不进行 Trivy 扫描）
./bin/kubesentinel scan --collect-only --output reports/
```
### CLI 选项
| 标志 | 描述 | 默认值 |
|------|-------------|---------|
| `-c, --config` | YAML 配置文件路径 | 自动发现 |
| `--kubeconfig` | kubeconfig 路径 | `~/.kube/config` |
| `-o, --output` | 输出目录 | `reports/` |
| `-n, --namespace` | 要扫描的 namespace | 全部 |
| `-w, --workers` | 并行 worker 数 | `8` |
| `--sbom` | 使用 Syft 生成 SBOM | `false` |
| `--cosign` | 使用 Cosign 验证签名 | `false` |
| `--collect-only` | 跳过漏洞扫描 | `false` |
| `--log-level` | 日志级别 | `info` |
## 配置文件
您可以使用 YAML 配置文件，而无需每次都传递标志。KubeSentinel 会按以下顺序查找该文件：
1. `--config /path/to/config.yaml`（显式指定）
2. `./kubesentinel.yaml`（当前目录）
3. `~/.config/kubesentinel/config.yaml`（用户全局配置）
```
# ~/.config/kubesentinel/config.yaml
output: ~/kubesentinel-reports/
workers: 16
namespaces:
- production
- staging
sbom: true
cosign: false
logLevel: info
```
CLI 标志始终会覆盖配置文件中的值。有关所有选项，请参见 `kubesentinel.example.yaml`。
## Docker
```
# 构建镜像
docker build -t kubesentinel .
# 针对您的 cluster 运行（挂载 kubeconfig 和报告目录）
docker run --rm \
-v ~/.kube/config:/home/kubesentinel/.kube/config:ro \
-v "$(pwd)/reports:/reports" \
kubesentinel scan --kubeconfig /home/kubesentinel/.kube/config --output /reports
```
该镜像内置了 Trivy，因此漏洞扫描可以直接开箱即用。
## GitHub Action
在 CI 中使用 KubeSentinel 定期扫描您的集群：
```
name: Cluster Security Scan
on:
schedule:
- cron: '0 6 * * 1' # every Monday 06:00 UTC
workflow_dispatch:
jobs:
scan:
runs-on: ubuntu-latest
steps:
- uses: azure/k8s-set-context@v4
with:
kubeconfig: ${{ secrets.KUBECONFIG }}
- uses: mustafa0766/kubesentinel@v1
with:
namespaces: production,staging
workers: 16
sbom: true
```
报告将作为 workflow artifact（`kubesentinel-reports`）上传。
## 安全评分
每个镜像都会获得一个 0 到 100 之间的分数：
| 因素 | 扣分 |
|--------|---------|
| 严重 CVE | 每个 -10 |
| 高危 CVE | 每个 -5 |
| 以 Root 身份运行 | -10 |
| `latest` 标签 | -5 |
| 未签名镜像 | -10 |
| EOL 操作系统 | -10 |
| 特权容器 | -15 |
| 主机网络 | -10 |
## 输出
扫描完成后，输出目录将包含：
```
reports/
├── kubesentinel-20260716-120000.html # Interactive dashboard
├── kubesentinel-20260716-120000.json # Full JSON report
├── kubesentinel-20260716-120000.csv # Spreadsheet-friendly summary
└── sbom/ # SBOM files (if --sbom)
└── nginx_latest_cyclonedx-json.json
```
## 项目结构
```
kubesentinel/
├── cmd/kubesentinel/ # CLI entrypoint
├── internal/
│ ├── kubernetes/ # K8s client & image collector
│ ├── scanner/ # Trivy, Syft, Cosign integrations + worker pool
│ ├── analyzer/ # Scoring, OS/vendor/base-image detection
│ ├── report/ # HTML, CSV, JSON generators
│ ├── models/ # Data models
│ ├── config/ # YAML config file loading
│ └── cmd/ # Cobra commands
├── test/e2e/ # End-to-end tests (e2e build tag)
│ └── fixtures/ # Test workloads for kind-based CI
├── .github/workflows/ # CI, E2E (kind), and release pipelines
├── reports/ # Default output directory
├── Dockerfile # Multi-stage image with bundled Trivy
├── action.yml # GitHub Action definition
├── kubesentinel.example.yaml # Example config file
├── Makefile
└── README.md
```
## 路线图
- [x] **v0.1 (MVP)** — 镜像收集、Trivy 扫描、JSON/CSV 报告
- [x] **v0.2** — HTML 仪表板、安全评分、namespace 摘要
- [x] **v0.3** — Syft SBOM、Cosign 验证、基础镜像分析
- [x] **v1.0** — 并行扫描（Trivy 服务器模式）、配置文件、Docker 镜像、GitHub Action、端到端测试
- [ ] **下一步** — Homebrew formula、GitHub Release 自动化验证、策略引擎（用于 CI 的失败阈值）
## 开发
```
make test # Run unit tests
make e2e # Run end-to-end tests against current kubeconfig context
make e2e-full # e2e including real Trivy scan (slow)
make lint # Run linters
make build # Build binary
make run # Scan current cluster
```
### 端到端测试
端到端测试位于 `test/e2e/` 目录下，并在 `e2e` 构建标签之后，因此 `make test` 永远不会触碰集群。它们使用当前的 kubeconfig 上下文，如果无法连接到集群，则会**自动跳过**。
| 测试 | 验证内容 |
|------|------------------|
| `TestE2E_ClusterConnection` | Kubeconfig 加载与 API 连通性 |
| `TestE2E_CollectImages` | 针对单个 namespace 的镜像收集和使用元数据 |
| `TestE2E_CollectAllNamespaces` | 跨所有 namespace 的全集群清单 |
| `TestE2E_ReportGeneration` | JSON/CSV/HTML 报告的生成与有效性 |
| `TestE2E_FullScanWithTrivy` | 通过工作池进行真实的 Trivy 扫描（可选启用） |
通过环境变量进行配置：
```
# 扫描不同的 namespace（默认：kube-system）
KUBESENTINEL_E2E_NAMESPACE=production make e2e
# 包含真实的 Trivy 漏洞扫描
make e2e-full
```
## 许可证
MIT
标签：DevSecOps, EVTX分析, Go, GraphQL安全矩阵, LLM防护, Ruby工具, SBOM, 上游代理, 子域名突变, 安全扫描器, 日志审计, 硬件无关, 请求拦截