# Scanning Kubernetes Manifests With Kubesec

> 使用 Kubesec 对 Kubernetes 资源清单执行安全风险分析，识别错误配置、权限提升风险以及与安全最佳实践的偏差。

- Skill: `killvxk/scanning-kubernetes-manifests-with-kubesec` (Agent Skill, multi-file: 8 files)
- Install (CLI): `npx skillmds@latest add killvxk/scanning-kubernetes-manifests-with-kubesec`
- Raw SKILL.md: https://api.skillmd.com/api/skills/killvxk/scanning-kubernetes-manifests-with-kubesec/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- License: Apache-2.0
- Author: killvxk (https://skillmd.com/u/killvxk)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/killvxk/scanning-kubernetes-manifests-with-kubesec

---


# 使用 Kubesec 扫描 Kubernetes 清单

## 概述

Kubesec 是由 ControlPlane 开发的开源安全风险分析工具，用于检查 Kubernetes 资源清单中常见的可利用风险，如权限提升（Privilege Escalation）、可写宿主机挂载和过多能力赋予。它为每个资源分配数值安全评分，并提供可操作的加固建议。Kubesec 可作为 CLI 二进制、Docker 容器、kubectl 插件、准入 Webhook 或 REST API 端点使用。

## 前置条件

- Kubernetes 清单文件（YAML/JSON），适用于 Deployment、Pod、DaemonSet、StatefulSet
- 本地安装需要 Docker 或 Go 运行时
- kubectl 访问权限（用于扫描集群中的实时资源）
- CI/CD 流水线访问权限（用于自动化扫描集成）

## 核心概念

### 安全评分系统

Kubesec 根据安全检查为每个 Kubernetes 资源分配评分：

- **正分**：对安全增强配置的奖励（readOnlyRootFilesystem、runAsNonRoot）
- **零分或负分**：表示缺少安全控制或存在危险配置
- **关键建议（Critical advisories）**：标记代表即时安全风险的配置

### 检查类别

1. **特权控制**：检查特权容器、宿主机 PID/网络访问、root 执行
2. **能力（Capabilities）**：识别过多的 Linux 能力（SYS_ADMIN、NET_RAW）
3. **卷挂载**：检测危险的宿主机路径挂载和可写的敏感路径
4. **资源限制**：验证 CPU/内存资源限制的存在
5. **安全上下文**：验证 seccomp 配置文件、AppArmor 注解、SELinux 上下文

## 安装

### 二进制安装

```bash
# Linux/macOS
curl -sSL https://github.com/controlplaneio/kubesec/releases/latest/download/kubesec_linux_amd64.tar.gz | \
  tar xz -C /usr/local/bin/ kubesec

# 验证安装
kubesec version
```

### Docker 安装

```bash
docker pull kubesec/kubesec:v2

# 扫描清单文件
docker run -i kubesec/kubesec:v2 scan /dev/stdin < deployment.yaml
```

### kubectl 插件

```bash
kubectl krew install kubesec-scan
kubectl kubesec-scan pod mypod -n default
```

## 实践扫描

### 扫描单个清单

```bash
# 扫描 deployment 清单
kubesec scan deployment.yaml

# 以 JSON 格式输出
kubesec scan -o json deployment.yaml

# 从标准输入扫描
cat pod.yaml | kubesec scan -
```

### 示例输出

```json
[
  {
    "object": "Pod/web-app.default",
    "valid": true,
    "fileName": "pod.yaml",
    "message": "Passed with a score of 3 points",
    "score": 3,
    "scoring": {
      "passed": [
        {
          "id": "ReadOnlyRootFilesystem",
          "selector": "containers[] .securityContext .readOnlyRootFilesystem == true",
          "reason": "不可变根文件系统可防止应用向本地磁盘写入",
          "points": 1
        },
        {
          "id": "RunAsNonRoot",
          "selector": "containers[] .securityContext .runAsNonRoot == true",
          "reason": "强制运行的镜像以非 root 用户运行",
          "points": 1
        },
        {
          "id": "LimitsCPU",
          "selector": "containers[] .resources .limits .cpu",
          "reason": "强制 CPU 限制可防止通过资源耗尽实施 DoS 攻击",
          "points": 1
        }
      ],
      "advise": [
        {
          "id": "ApparmorAny",
          "selector": "metadata .annotations .\"container.apparmor.security.beta.kubernetes.io/nginx\"",
          "reason": "定义良好的 AppArmor 策略可减少容器攻击面",
          "points": 3
        },
        {
          "id": "ServiceAccountName",
          "selector": ".spec .serviceAccountName",
          "reason": "服务账户限制 Kubernetes API 访问，应进行配置",
          "points": 3
        }
      ]
    }
  }
]
```

### 扫描多个资源

```bash
# 扫描目录中所有 YAML 文件
for file in manifests/*.yaml; do
  echo "=== 扫描 $file ==="
  kubesec scan "$file"
done

# 扫描多文档 YAML
kubesec scan multi-resource.yaml
```

### 使用 HTTP API

```bash
# 通过公共 API 扫描
curl -sSX POST --data-binary @deployment.yaml \
  https://v2.kubesec.io/scan

# 运行本地 API 服务器
kubesec http --port 8080 &

# 对本地服务器扫描
curl -sSX POST --data-binary @deployment.yaml \
  http://localhost:8080/scan
```

## CI/CD 集成

### GitHub Actions

```yaml
name: Kubesec 扫描
on: [pull_request]
jobs:
  kubesec:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: 安装 Kubesec
        run: |
          curl -sSL https://github.com/controlplaneio/kubesec/releases/latest/download/kubesec_linux_amd64.tar.gz | \
            tar xz -C /usr/local/bin/ kubesec
      - name: 扫描清单
        run: |
          FAIL=0
          for file in k8s/*.yaml; do
            SCORE=$(kubesec scan "$file" | jq '.[0].score')
            echo "$file: score=$SCORE"
            if [ "$SCORE" -lt 0 ]; then
              echo "FAIL: $file 存在严重问题（评分：$SCORE）"
              FAIL=1
            fi
          done
          exit $FAIL
```

### GitLab CI

```yaml
kubesec-scan:
  stage: security
  image: kubesec/kubesec:v2
  script:
    - |
      for file in k8s/*.yaml; do
        kubesec scan "$file" > /tmp/result.json
        SCORE=$(cat /tmp/result.json | jq '.[0].score')
        if [ "$SCORE" -lt 0 ]; then
          echo "严重：$file 评分 $SCORE"
          cat /tmp/result.json | jq '.[0].scoring.critical'
          exit 1
        fi
      done
  artifacts:
    paths:
      - kubesec-results/
```

### 准入 Webhook

将 Kubesec 部署为 ValidatingWebhookConfiguration，在部署时拒绝不安全的清单：

```yaml
apiVersion: admissionregistration.k8s.io/v1
kind: ValidatingWebhookConfiguration
metadata:
  name: kubesec-webhook
webhooks:
  - name: kubesec.controlplane.io
    rules:
      - apiGroups: [""]
        apiVersions: ["v1"]
        operations: ["CREATE", "UPDATE"]
        resources: ["pods"]
      - apiGroups: ["apps"]
        apiVersions: ["v1"]
        operations: ["CREATE", "UPDATE"]
        resources: ["deployments", "daemonsets", "statefulsets"]
    clientConfig:
      service:
        name: kubesec-webhook
        namespace: kube-system
        path: /scan
    failurePolicy: Fail
    sideEffects: None
    admissionReviewVersions: ["v1"]
```

## 安全检查参考

### 严重检查（负分）

| 检查项 | 选择器 | 风险 |
|-------|----------|------|
| 特权模式 | `securityContext.privileged == true` | 完整宿主机访问 |
| HostPID | `spec.hostPID == true` | 进程命名空间逃逸 |
| HostNetwork | `spec.hostNetwork == true` | 网络命名空间逃逸 |
| SYS_ADMIN | `capabilities.add contains SYS_ADMIN` | 接近 root 的能力 |

### 最佳实践检查（正分）

| 检查项 | 分值 | 描述 |
|-------|--------|-------------|
| ReadOnlyRootFilesystem | +1 | 防止文件系统写入 |
| RunAsNonRoot | +1 | 非 root 进程执行 |
| RunAsUser > 10000 | +1 | 高 UID 降低冲突风险 |
| LimitsCPU | +1 | 防止 CPU 资源耗尽 |
| LimitsMemory | +1 | 防止内存资源耗尽 |
| RequestsCPU | +1 | 确保调度器资源感知 |
| ServiceAccountName | +3 | 显式服务账户 |
| AppArmor 注解 | +3 | 内核级 MAC 执行 |
| Seccomp 配置文件 | +4 | 系统调用过滤 |

## 参考资料

- [Kubesec GitHub 仓库](https://github.com/controlplaneio/kubesec)
- [Kubesec 在线扫描器](https://kubesec.io/)
- [ControlPlane 安全工具](https://controlplane.io/)
- [CIS Kubernetes Benchmark](https://www.cisecurity.org/benchmark/kubernetes)
- [Kubernetes Pod 安全标准](https://kubernetes.io/docs/concepts/security/pod-security-standards/)