kubeguard-mcp
This MCP server statically audits Kubernetes YAML manifests for security, correctness, and cross-resource risks.
kubeguard_scan— audit manifest text and return findings withpath:lineevidence.kubeguard_scan_path— audit every YAML file under a local directory.kubeguard_rules— list all 37 rules with severity, rationale, and fix guidance.kubeguard_rbac— resolve bindings and report effective permissions per subject.kubeguard_demo— write a vulnerable sample manifest and audit it as a self-check.
Generates SARIF output suitable for upload to GitHub code scanning, so audit findings appear as code-scanning alerts in a repository's CI workflow.
Audits Kubernetes YAML manifests with 37 deterministic rules, producing findings with file:line evidence. Supports scanning files or directories, resolving RBAC bindings into effective per-subject permissions, and analyzing cross-resource relationships like NetworkPolicy coverage, Service/Ingress wiring, and privilege-escalation combinations.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@kubeguard-mcp scan my manifests in ./k8s for critical issues and show the file:line evidence"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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-demoContents
Related MCP server: MCP DevOps Toolbox
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.
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 aboveNo 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 RISKCommands
Command | What it does |
| audit files or directories; |
| print the catalogue ( |
| resolve bindings → what each subject can actually do |
| the cross-resource view: labels, selectors, policies |
| write a deliberately broken manifest and audit it |
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.sarifSuppression
Two file-local mechanisms, both visible in a diff:
privileged: true # kubeguard: ignore=KG001kubeguard scan . --ignore KG016,KG025 # digest pinning / labels not our policyMCP server
uvx --from "kubeguard[mcp]" kubeguard-mcpTool | Purpose |
| audit manifest text, with evidence |
| audit a directory |
| the catalogue, with why/fix |
| effective permissions per subject |
| self-check that the rules fire |
中文说明
唯一读「对象之间关系」的 Kubernetes 清单审计器。 37 条确定性规则 · 零依赖 ·
每条结论带 文件:行号 · SARIF 直连 GitHub Code Scanning · 内置 MCP server。
为什么还要做一个
kube-linter(3.5k★)是 Go 写的,规则基本是单对象检查:看一个 Deployment,
判断它的 securityContext 对不对。但 Kubernetes 的默认策略是全通,真正的风险
往往只在两个对象的关系里成立:
没有 NetworkPolicy 选中这个 Deployment —— 集群里任何 Pod 都能直连它。 单看 Deployment,它完全合规。
Service 的 selector 打错了字 —— 服务零后端,单看 Service 也完全合规。
一个 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
Group | Rules | Covers |
| 25 | privileged、运行时 socket、hostPID/IPC/Network、allowPrivilegeEscalation、runAsNonRoot、高危 capability、NET_RAW、只读根文件系统、hostPath、hostPort、limits/requests、可变 tag、摘要锁定、拉取策略、就绪/存活探针、seccomp、SA token 自动挂载、default SA、明文密钥、废弃 API、推荐标签 |
| 6 | 通配 verbs/resources/apiGroups、secrets 读取、pods/exec、escalate·bind·impersonate、cluster-admin 绑定 |
| 6 | NetworkPolicy 覆盖、Service selector 落空、Ingress 后端缺失、SA 未定义、权限组合提权、namespace 无配额 |
kubeguard rules 打印完整目录(含每条的 why / fix / CWE)。
已知边界
不支持 YAML 锚点(
&x/*x)与合并键(<<:);遇到无法解析的行会直接报YamlError并记进summary.errors,不会静默跳过半份清单。RBAC 分析是清单内的:集群里已存在但不在本次扫描范围内的 Role 不在视野内。
cluster-admin等内置角色做了特判。只做静态分析,不做 CVE 匹配、不做镜像扫描。
许可证
MIT
Available Tools
5 toolskubeguard_demoC
Write a vulnerable sample manifest and audit it.
Inputs: directory.
kubeguard_rbacC
Effective permissions per subject after resolving all bindings.
Inputs: path.
kubeguard_rulesA
List every rule with severity, rationale and fix.
Inputs: no named parameters.
kubeguard_scanB
Audit Kubernetes manifest text. Returns findings with path:line evidence.
Inputs: path, content.
kubeguard_scan_pathC
Audit every YAML file under a local directory.
Inputs: path.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
kubeguard_scan (inline manifest text) and kubeguard_scan_path (directory of YAML files) share the auditing purpose but have clearly different inputs, and the descriptions make that distinction explicit. kubeguard_demo also produces an audit but is framed as sample generation, so it is unlikely to be misselected. Only the scan/scan_path pair presents mild ambiguity.
All tools use a uniform kubeguard_ snake_case prefix, which makes the family immediately recognizable. The suffix style mixes verbs (scan, scan_path, demo) with nouns (rules, rbac), a minor deviation from a pure verb_noun pattern but still readable and predictable.
Five tools is well-scoped for a focused Kubernetes manifest auditor, and each tool covers a distinct capability: text scan, directory scan, rule catalog, RBAC analysis, and demo. There is no redundant or filler tool.
The set covers the core audit lifecycle: discovering rules, scanning inputs in two forms, analyzing RBAC, and a demo entry point for onboarding. Gaps are minor for a read-only auditor, but there is no way to apply or export fixes, suppress/config rules, or scan a live cluster, so agents must handle remediation outside the server.
Maintenance
Related MCP Connectors
Fail-closed policy guardrails for AI agents running kubectl, terraform, helm, and argocd.
Scan configs, files, or text for leaked secrets and obvious misconfigurations. Nothing stored.
IaC, CI and dependency security review for coding agents: local scan CLI plus hosted OAuth MCP.
IaC attack-path auditor: finds internet-to-crown-jewel chains in Terraform/CFN/K8s.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables analyzing Salesforce deployment logs, validating metadata manifests, assessing permission risks, and generating remediation plans through deterministic, local-only rules.4MIT
- AlicenseNot gradedqualityCmaintenanceEnables safe, local DevOps inspection through a JSON-lines server with schema validation, path isolation, and redaction, supporting read-only Git operations, Kubernetes YAML validation, Terraform plan summaries, and sanitized log analysis.MIT
- AlicenseAqualityCmaintenanceEnables agents and users to validate Kubernetes manifests (YAML/JSON, multi-document) against the API of a chosen Kubernetes version without needing a cluster. It reports removed or deprecated APIs with replacements, unknown or misspelt fields, misconfigurations the API server would reject, Pod Security Standard violations, and common risks, each with file, line, and fix.31MIT
- AlicenseNot gradedqualityBmaintenanceEnables read-only inspection of Kubernetes resources and Terraform plans, retrieval of policy findings, and schema and policy validation of manifests and patches without applying changes.MIT