kubeguard

Kubernetes manifest audit that reads the relationships, not just the objects. 37 deterministic rules · zero dependencies · every finding carries file:line · SARIF straight into GitHub code scanning · MCP server for Claude Code / Cursor.

kubeguard demo && kubeguard scan ./kubeguard-demo

The one thing it does that nothing else does

Kubernetes' default is allow all, and most of its worst failures live in the space between two objects:

kind: Deployment          # L15: no NetworkPolicy selects these labels
spec:
  template:
    metadata:
      labels: {app: web}  # <- every pod in the cluster can reach it
---
kind: Service             # L24: selector says app: webby
spec:
  selector: {app: webby}  # <- typo. The Service has zero backends.
---
kind: ClusterRole         # L40: create on clusterroles
rules:
  - verbs: [create]
    resources: [clusterroles]
  - verbs: [escalate]     # <- harmless alone. With the line above: cluster takeover.

A single-object linter cannot see any of those three. kubeguard runs a third pass over the whole manifest set — NetworkPolicy coverage, Service/Ingress wiring, and RBAC resolved through every binding into what each subject can actually do.

Related MCP server: MCP DevOps Toolbox

Quick start (3 steps)

pip install kubeguard

kubeguard demo                      # 1. write a broken manifest, audit it
kubeguard scan .                    # 2. audit your own manifests
kubeguard scan . --fail-on high     # 3. CI gate: exit 1 on high or above

No cluster, no kubectl, no API server. It reads YAML files, which is what makes it usable in a CI job that has none of those things.

Output

kubeguard  deployment.yaml

deployment.yaml
  CRITICAL KG002  Container runtime socket mounted
      deployment.yaml:21  prod:Deployment/payments
      挂载运行时 socket：/var/run/docker.sock
      > - name: dockersock
      fix: 删除该 hostPath 卷。
  CRITICAL KG001  Privileged container
      deployment.yaml:38  prod:Deployment/payments[container/api]
      容器 api 以 privileged 运行
      > privileged: true
  HIGH     KG040  Workload not covered by any NetworkPolicy
      deployment.yaml:3   prod:Deployment/payments
      没有任何 NetworkPolicy 选中它

11 critical, 18 high, 28 medium, 17 low, 8 info  ·  9 resources  ·  4 workloads
risk 100/100  CRITICAL RISK

Commands

Exit codes: 0 clean · 1 findings at/above --fail-on · 2 the scan failed.

CI

- run: pip install kubeguard
- run: kubeguard scan ./manifests --fail-on high --format sarif --output kubeguard.sarif
- uses: github/codeql-action/upload-sarif@v3
  if: always()
  with:
    sarif_file: kubeguard.sarif

Suppression

Two file-local mechanisms, both visible in a diff:

      privileged: true   # kubeguard: ignore=KG001

kubeguard scan . --ignore KG016,KG025   # digest pinning / labels not our policy

MCP server

uvx --from "kubeguard[mcp]" kubeguard-mcp

中文说明

唯一读「对象之间关系」的 Kubernetes 清单审计器。 37 条确定性规则 · 零依赖 · 每条结论带 文件:行号 · SARIF 直连 GitHub Code Scanning · 内置 MCP server。

为什么还要做一个

kube-linter（3.5k★）是 Go 写的，规则基本是单对象检查：看一个 Deployment， 判断它的 securityContext 对不对。但 Kubernetes 的默认策略是全通，真正的风险 往往只在两个对象的关系里成立：

1. 没有 NetworkPolicy 选中这个 Deployment —— 集群里任何 Pod 都能直连它。 单看 Deployment，它完全合规。

2. Service 的 selector 打错了字 —— 服务零后端，单看 Service 也完全合规。

3. 一个 Role 里同时有 create clusterroles 和 escalate —— 单独看每一条 都像是日常权限，合起来是完整的集群接管链。

这三条，任何「一次只读一个对象」的 linter 都报不出来。kubeguard 因此跑第三遍扫描： 把 RoleBinding 解析成主体，把每个主体的权限取并集，再判断组合是否危险；同时做 NetworkPolicy 覆盖、Service/Ingress 连通性、ServiceAccount 存在性检查。

三步跑通

pip install kubeguard

kubeguard demo                      # 1. 写一份故意写错的清单并审计它
kubeguard scan .                    # 2. 审计自己的 manifests
kubeguard scan . --fail-on high     # 3. CI 闸门：命中 high 就 exit 1

不需要集群、不需要 kubectl、不需要连 API Server —— 它只读 YAML 文件。

设计取舍

• 零第三方依赖。自带缩进式 YAML 读取器（yamlio.py），代价是不支持锚点/别名， 收益是每个标量都保留自己所在的行号，结论才能指到 deployment.yaml:38。

• PodSpec 归一化。Pod / Deployment / StatefulSet / DaemonSet / Job / CronJob 的 PodSpec 藏在六个不同路径下；这里按形状识别（哪里挂着 containers）， 不写死 (apiVersion, kind) 组合，所以 beta 组也能覆盖。

• initContainer 一样审。它先于应用运行、权限相同，最常被漏掉。

• securityContext 两级合并。容器级优先，pod 级兜底 —— 只查容器级会对 「在 pod 级统一配置」这种正确写法大量误报。

Rule map

kubeguard rules 打印完整目录（含每条的 why / fix / CWE）。

已知边界

• 不支持 YAML 锚点（&x / *x）与合并键（<<:）；遇到无法解析的行会直接报 YamlError 并记进 summary.errors，不会静默跳过半份清单。

• RBAC 分析是清单内的：集群里已存在但不在本次扫描范围内的 Role 不在视野内。 cluster-admin 等内置角色做了特判。

• 只做静态分析，不做 CVE 匹配、不做镜像扫描。

许可证

MIT