Kubescape 架构深度解析CLI 扫描与集群 Operator 双模式下的模块化 Kubernetes 安全平台【免费下载链接】kubescapeKubescape is an open-source Kubernetes security platform for your IDE, CI/CD pipelines, and clusters. It includes risk analysis, security, compliance, and misconfiguration scanning, saving Kubernetes users and administrators precious time, effort, and resources.项目地址: https://gitcode.com/GitHub_Trending/ku/kubescape导读本文基于仓库内 docs/architecture.md 官方架构文档结合 Kubescape 源码命令层、核心引擎、OPA 策略处理器、镜像扫描器等展开讲解Kubescape 如何以CLI 按需扫描与集群内 Operator 持续监控两种模式运行两种模式如何共享同一套核心扫描逻辑却又在数据采集与结果上报上分道扬镳。读完本文你将理解 Kubescape 的整体分层设计、策略评估OPA/Rego与镜像漏洞扫描Grype/Syft、镜像补丁Copacetic的底层流水线以及框架/控制项、扩展点、安全模型等关键机制并能在实际部署中正确选择模式与配置。一、总体架构两种模式一套核心Kubescape 被设计为一个模块化安全平台支持两种主要运行模式见 docs/architecture.mdCLI 模式从本地机器按需发起扫描输出报告到终端或文件Operator 模式作为 Kubernetes 工作负载常驻集群内提供持续安全监控。两种模式共享核心扫描逻辑策略评估、控制项判定、结果聚合差异集中在数据采集方式与结果上报路径CLI 通过 kubeconfig 访问集群、读取本地 YAML/Helm/Kustomize/Git 仓库等输入结果输出到控制台或本地文件Operator 通过集群内的控制器监听资源变化、按调度触发扫描并将结果持久化为自定义资源CR。这种共享核心、差异外围的设计使得 CLI 与 Operator 能够各自演进同时保证扫描语义的一致性。二、CLI 架构Kubescape CLI 是一个独立二进制按需执行安全评估。其整体结构如下图所示来源docs/img/ks-cli-arch.png2.1 命令层cmd/命令层是所有 CLI 操作的入口。所有子命令在 cmd/root.go 中通过rootCmd.AddCommand(...)注册实际可用的命令比架构文档列出的还要丰富。下表整理了架构文档中的核心命令并补充了源码中确认的关键能力命令说明源码佐证scan编排配置错误与漏洞扫描包含framework/control/workload/image子命令cmd/scan/scan.goscan image容器镜像漏洞扫描cmd/scan/image.gofix基于扫描报告对配置错误进行自动修复manifest 就地修改cmd/fix/fix.gopatch使用 Copa BuildKit 对容器镜像打补丁cmd/patch/patch.golist列出可用的框架framework与控制项controlcmd/list/list.godownload预下载离线/气隙环境所需工件cmd/download/download.govapValidating Admission Policy 管理cmd/vap/vap.gomcpserver面向 AI 集成MCP 协议的服务端cmd/mcpserver/mcpserver.gooperator与集群内 Operator 通信scan/remediate子命令cmd/operator/operator.goconfig/update/diff/decrypt/policy/prerequisites/completion/version配置管理、自更新、报告对比、报告解密、策略测试等辅助能力cmd/root.go从源码看scan命令的典型用法非常丰富cmd/scan/scan.go# 扫描当前集群 kubescape scan # 扫描本地 Kubernetes manifest 文件 kubescape scan . # 一次扫描输出多种格式 kubescape scan --format json,html,junit --output result # 扫描不同 kube-context 下的集群 kubescape scan --kube-context kubernetes context # 基于基线报告做漂移检测CI 中出现新的高危问题时失败 kubescape scan --baseline base.json --baseline-fail-on-new --baseline-severity-threshold highscan命令还支持大量细粒度控制参数例如--include-namespaces/--exclude-namespaces、--include-kinds/--exclude-kinds、--exclude-controls/--include-controls、--compliance-threshold合规率低于阈值退出码为 1、--severity-threshold按严重度决定 CI 是否失败、--controls-version锁定 regolibrary 发布标签、--scan-timeout/--control-timeout全局与单控制项超时、--enable-streaming大集群分批处理资源等详见 cmd/scan/scan.go。2.2 核心引擎core/核心引擎承担扫描生命周期的主要阶段。在 core/core/scan.go 的ScanContext中可以看到一条清晰的调用链初始化Initialization解析扫描目标与策略标识符resolveDefaultScanAllPolicies、初始化ScanInfo、解析集群上下文、装配 k8s 接口、租户配置、宿主传感器、资源处理器、报告器与输出打印机等组件getInterfaces策略收集Policies通过policyHandler.CollectPolicies拉取框架与控制项定义同时加载 control-inputs配置输入与 exceptions例外项支持本地缓存回退controlInputsFromCache/exceptionsFromCache资源收集Resources从集群或本地文件收集 Kubernetes 资源对于超过 2500 个资源的大集群会自动启用流式处理estimateClusterSizecautils.IsLargeCluster判断分批采集与评估以降低内存占用OPA 评估opaprocessor.NewOPAProcessor(...).ProcessRulesListener(...)驱动 Rego/CEL 规则执行资源优先级排序Prioritization基于攻击路径Attack Tracks做资源优先级评估可输出攻击树--print-attack-tree镜像扫描可选scanInfo.ScanImages时并行扫描工作负载镜像结果处理Results Handling聚合结果支持--hide匿名化与--encrypt加密AES-256 Argon2id 派生密钥见 core/pkg/reportcrypto再交给打印机输出。其中getInterfacescore/core/scan.go清晰地展示了核心引擎的组件装配k8s 接口、租户配置TenantConfig、资源处理器ResourceHandler、报告器Reporter、UI 打印机与输出打印机Printer、宿主传感器HostSensorHandler六类组件。2.3 策略评估OPA/RegoKubescape 使用 Open Policy AgentOPA作为策略引擎评估流程如下┌─────────────────────────────────────────────────────────────┐ │ Policy Evaluation Flow │ ├─────────────────────────────────────────────────────────────┤ │ │ │ K8s Resources ──► OPA Engine ──► Rego Policies ──► Results │ │ │ │ │ │ │ ▼ │ │ │ Regolibrary │ │ │ (Control Library) │ │ │ │ │ ▼ │ │ - YAML files │ │ - Helm charts │ │ - Live cluster │ │ - Git repositories │ │ │ └─────────────────────────────────────────────────────────────┘**Regolibrary控制库**是策略内容的来源包含安全控制项200框架定义NSA-CISA、MITRE ATTCK®、CIS Benchmarks 等控制元数据与修复remediation指导在源码层面OPA 处理器位于 core/pkg/opaprocessor/processorhandler.go其包注释明确说明该引擎消费 regolibrary 仓库定义的规则并产出 Kubescape 的配置错误结果同时支持 Rego 规则评估与 CEL 规则分发CEL 引擎见 core/pkg/opaprocessor/cel。处理器还实现了若干关键机制单控制项超时ControlTimeout非零时单个控制项评估超时会被标记为未评估而不是拖垮整个扫描全集群输入控制某些控制项如跨命名空间的 RoleBinding 关联控制 ID C-0261/C-0266/C-0267/C-0272必须基于全集群数据评估处理器通过requiresWholeClusterInput属性与内置回退表processorhandler.go保证这类控制不会被逐命名空间评估所破坏增量缓存--incremental开启时按资源 spec/metadata 哈希与 controls-config 版本缓存判定结果跳过未变更资源的重复评估。2.4 镜像扫描器Grype 集成漏洞扫描方面Kubescape 集成 Grype 作为漏洞匹配引擎流水线如下┌─────────────────────────────────────────────────────────────┐ │ Image Scanning Pipeline │ ├─────────────────────────────────────────────────────────────┤ │ │ │ Container Image ──► SBOM Generation ──► Vulnerability DB │ │ │ │ │ │ ▼ ▼ │ │ Syft Engine Grype Matching │ │ │ │ │ │ └────────┬───────────┘ │ │ ▼ │ │ CVE Results │ │ │ └─────────────────────────────────────────────────────────────┘源码实现位于 pkg/imagescan/imagescan.go镜像先经Syft生成 SBOM软件物料清单再由Grype对照漏洞库匹配出 CVE默认漏洞库地址为https://grype.anchore.io/databases可通过--grype-db-url覆盖数据库缓存在$XDG_CACHE_HOME/grypedb目录--skip-db-update可跳过更新离线场景必备支持按生态分类的匹配器dotnet、golang、java、javascript、python、ruby 与 stock通用见 pkg/imagescan/imagescan.go支持私有仓库认证用户名/密码/token、--registry-mapping内网仓库地址映射、多平台镜像扫描--image-platform并可依据工作负载调度约束推断平台等能力相关逻辑在 core/core/scan.go 的scanImages中实现支持并发扫描--image-scan-concurrency并可从工作负载的imagePullSecrets解析仓库凭据仅限集群扫描场景。2.5 镜像补丁器Copacetic 集成针对存在漏洞的镜像Kubescape 集成Copaceticcopa配合 BuildKit 进行自动补丁流水线如下┌─────────────────────────────────────────────────────────────┐ │ Image Patching Pipeline │ ├─────────────────────────────────────────────────────────────┤ │ │ │ Vulnerable Image ──► Copa ──► BuildKit ──► Patched Image │ │ │ │ │ │ ▼ ▼ │ │ - Scan for CVEs - Apply OS patches │ │ - Identify fixes - Rebuild layers │ │ - Generate patch plan - Push to registry │ │ │ └─────────────────────────────────────────────────────────────┘对应命令为kubescape patchcmd/patch/patch.go其典型用法sudo buildkitd # 先启动 buildkitd 服务 sudo kubescape patch --image docker.io/library/nginx:1.22 # 对镜像打补丁源码中通过引入github.com/project-copacetic/copacetic/pkg/buildkitcmd/patch/patch.go与 BuildKit 交互完成 OS 级漏洞修复与镜像层重建。2.6 CLI 扫描数据流将输入源、处理与输出串起来CLI 扫描的完整数据流如下┌──────────────────────────────────────────────────────────────────────┐ │ CLI Scan Data Flow │ ├──────────────────────────────────────────────────────────────────────┤ │ │ │ Input Sources Processing Output │ │ ───────────── ────────── ────── │ │ │ │ ┌─────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ │ │ Kubernetes │────────►│ │ │ Console │ │ │ │ Cluster │ │ │───►│ (pretty-print) │ │ │ └─────────────┘ │ │ └─────────────────┘ │ │ │ │ │ │ ┌─────────────┐ │ Kubescape │ ┌─────────────────┐ │ │ │ YAML Files │────────►│ Core Engine │───►│ JSON/SARIF │ │ │ └─────────────┘ │ │ └─────────────────┘ │ │ │ │ │ │ ┌─────────────┐ │ │ ┌─────────────────┐ │ │ │ Helm Charts │────────►│ │───►│ HTML/PDF │ │ │ └─────────────┘ │ │ └─────────────────┘ │ │ │ │ │ │ ┌─────────────┐ │ │ ┌─────────────────┐ │ │ │ Git Repos │────────►│ │───►│ JUnit XML │ │ │ └─────────────┘ └─────────────────┘ └─────────────────┘ │ │ │ └──────────────────────────────────────────────────────────────────────┘输入侧CLI 同时支持活动集群、YAML/JSON manifest 文件支持 glob 与 stdin-、Helm 图表含--values/--set/--set-string/--set-file等镜像 Helm 的参数透传见 cmd/scan/scan.go、Kustomize 目录与 Git 仓库。输出侧默认 pretty-printer另支持 json、html、junit、sarif 及 SBOMcyclonedx/spdx需--scan-images等格式且可多格式一次输出--format json,html,junit每个格式还可追加--show-evidence展示证据路径与字段值、--show-secrets等选项。三、Operator 架构集群内Kubescape Operator 在集群内提供持续安全监控其架构如下图所示来源docs/img/ks-operator-arch.png3.1 组件总览Operator 模式的组件划分如下1. Kubescape Operator主控制器监听 Kubernetes 资源变化按调度或按需触发扫描管理扫描生命周期将结果存储为自定义资源CR。在 CLI 侧kubescape operator scan子命令用于触发集群内 Operator 执行扫描cmd/operator/operator.go# 触发配置扫描 kubescape operator scan configurations # 触发漏洞扫描 kubescape operator scan vulnerabilities # 预览扫描后的修复建议默认 dry-run kubescape operator remediate annotate --kind Deployment --target-namespace payments --name api --reason C-00162. Kubevuln镜像漏洞扫描扫描集群中运行的镜像生成 SBOM对照漏洞数据库匹配创建VulnerabilityManifest自定义资源。3. Host Scanner节点信息采集采集内核参数采集 kubelet 配置采集容器运行时设置采集文件权限。CLI 侧对应的宿主数据采集由--host-scan标志控制未指定时自动检测 node-agent CRD 并使用基于 CRD 的宿主传感器--host-scanfalse可显式关闭cmd/scan/scan.go。4. Storage存储Kubescape 使用自定义资源CRD存储扫描结果CRD说明VulnerabilityManifest镜像漏洞扫描结果VulnerabilityManifestSummary聚合的漏洞摘要WorkloadConfigurationScan配置错误扫描结果WorkloadConfigurationScanSummary聚合的配置摘要ApplicationProfile运行时行为画像NetworkNeighborhood观察到的网络连接5. Node Agent运行时安全Node Agent 通过 eBPF 采集内核事件仓库中 eBPF 相关实现见 core/pkg/hostsensorutils/ebpf流程如下┌─────────────────────────────────────────────────────────────┐ │ Runtime Security Flow │ ├─────────────────────────────────────────────────────────────┤ │ │ │ Kernel ──► eBPF Probes ──► Node Agent ──► Kubescape │ │ │ │ │ │ ▼ ▼ │ │ System calls - Process exec │ │ Network events - File access │ │ File operations - Network connections │ │ - Anomaly detection │ │ │ └─────────────────────────────────────────────────────────────┘3.2 Operator 数据流Operator 模式的数据流如下┌──────────────────────────────────────────────────────────────────────┐ │ Operator Data Flow │ ├──────────────────────────────────────────────────────────────────────┤ │ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │ │ │ Kubernetes │ │ Kubescape │ │ Custom Resources │ │ │ │ API Server │────►│ Operator │────►│ (Scan Results) │ │ │ └─────────────┘ └─────────────┘ └─────────────────────────┘ │ │ │ │ │ │ │ │ │ ▼ │ │ │ │ ┌─────────────────────────┐ │ │ │ │ │ Prometheus Metrics │ │ │ │ │ └─────────────────────────┘ │ │ │ │ │ │ │ ▼ ▼ ▼ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │ │ │ Kubevuln │ │ Node Agent │ │ External Integrations │ │ │ │ (Images) │ │ (Runtime) │ │ (ARMO Platform, etc.) │ │ │ └─────────────┘ └─────────────┘ └─────────────────────────┘ │ │ │ └──────────────────────────────────────────────────────────────────────┘可以看到Kubernetes API Server 驱动 Operator 主控制器主控制器将扫描结果写入自定义资源同时可暴露 Prometheus 指标供监控告警Kubevuln 与 Node Agent 分别负责镜像与运行时数据采集外部集成如 ARMO Platform可选地接收数据。四、框架Frameworks与控制项ControlsKubescape 依据安全框架评估资源4.1 支持的框架框架说明NSA-CISAKubernetes 加固指南Kubernetes Hardening GuidanceMITRE ATTCK®基于威胁的安全框架CIS Benchmarks互联网安全中心最佳实践SOC2服务组织控制 2HIPAA医疗健康合规要求PCI-DSS支付卡行业标准源码层面内置框架清单定义在 core/cautils/getter/datastructures.go// NativeFrameworks identifies all pre-built, native frameworks. var NativeFrameworks []string{allcontrols, nsa, mitre}kubescape scan framework nsa,mitre即基于该清单执行kubescape scan framework all会展开为全部内置框架。更多框架CIS、SOC2、HIPAA、PCI-DSS 等通过 regolibrary 下发可用kubescape list frameworks查看cmd/list/list.go。4.2 控制项结构每个控制项Control是一个结构化定义架构文档给出的示意如下Control: id: C-0005 name: API server insecure port is enabled description: Check if the API server insecure port is enabled frameworks: - NSA - MITRE severity: High remediation: | Disable the insecure port by setting --insecure-port0 rules: - rego: | # OPA/Rego policy code控制项包含 ID、名称、描述、所属框架、严重度、修复建议remediation与规则列表rules每个规则含 Rego 代码。仓库内 rules 目录存放了大量随仓库分发的规则样例每个规则目录均包含raw.rego策略代码与rule.metadata.json元数据例如 rules/approve-csr-v1/raw.rego、rules/escalate-roles-clusterroles-v1/raw.rego是学习控制项编写与kubescape policy test的良好参考。五、安全模型5.1 CLI 模式以执行用户的权限运行通过 kubeconfig 访问集群不在集群中保留持久状态结果存储在本地或发送到已配置的后端。需要留意的是kubescape scan默认不会把结果上报到后端只有显式传入--submit时才会上报到 Kubescape SaaScmd/scan/scan.go--keep-local可确保结果完全不外发。此外--hide/--encrypt可用于保护报告中的敏感元数据--dry-run可在正式扫描前预检当前凭据能否列出策略所需的全部资源类型core/core/scan.go。5.2 Operator 模式作为 Kubernetes 工作负载运行使用带定义 RBAC 的 ServiceAccount结果以自定义资源存储可选地向外部后端发送数据。5.3 网络要求组件出站连接CLI漏洞库更新、框架下载Operator漏洞库更新、可选后端离线/气隙所有工件可预先下载离线气隙场景是 Kubescape 的明确一等公民kubescape download artifacts可预先下载全部策略工件cmd/download/download.gokubescape scan --use-from 本地目录从本地加载策略对象源码中isAirGappedMode会据此完全禁用网络下载器core/core/scan.go镜像扫描可用--grype-db-url指向内部漏洞库镜像、--skip-db-update跳过在线更新。六、扩展性6.1 自定义控制项Custom Controls你可以用 Rego 编写自定义控制项架构文档给出的模板如下package armo_builtins import rego.v1 deny contains msga if { # Your custom policy logic input.kind Deployment not input.spec.template.spec.securityContext.runAsNonRoot msga : { alertMessage: Deployment should run as non-root, alertScore: 7, failedPaths: [spec.template.spec.securityContext.runAsNonRoot], fixPaths: [{path: spec.template.spec.securityContext.runAsNonRoot, value: true}] } }自定义规则的接入方式也已原生支持kubescape scan --custom-rules path可加载规则目录含raw.rego与rule.metadata.json、规则目录集合或裸*.rego文件cmd/scan/scan.go。仓库内 rules 目录提供了大量可直接参考的真实规则如 rules/modify-privileged-pods-v1/raw.rego、rules/weak-namespace-pod-rce-v1/raw.rego每个规则还附有完整的测试用例。6.2 集成点HTTP API编程式访问见 httphandler/README.mdMCP Server面向 AI 助手的集成见 docs/mcp-server.md。kubescape mcpserver通过 stdio 暴露漏洞清单查询、配置扫描结果查询、实时框架/RBAC/网络扫描与工作负载扫描等工具AI 助手如 Claude Desktop可在配置文件中直接挂载Prometheus Metrics监控与告警Webhook外部通知。kubescape scan --notify url支持将扫描摘要 POST 到 SlackBlock Kit或 Microsoft TeamsAdaptive CardWebhookcmd/scan/scan.go。七、总结与进一步阅读Kubescape 的架构精髓可以概括为以 OPA/Rego 策略引擎为核心以模块化命令层与核心引擎为骨架以 CLI 按需扫描与 Operator 持续监控为两种部署形态以 Grype/Syft、Copacetic/BuildKit 为镜像安全能力外延。理解这套架构有助于你在 CI/CD 流水线、本地开发与集群常态化监控等不同场景中正确选择运行模式与参数组合并基于自定义规则与各类集成点将 Kubescape 嵌入自身的安全体系。进一步阅读入门指南安装指南MCP Server 文档ARMO Platform 集成配置输出说明HTTP API 文档【免费下载链接】kubescapeKubescape is an open-source Kubernetes security platform for your IDE, CI/CD pipelines, and clusters. It includes risk analysis, security, compliance, and misconfiguration scanning, saving Kubernetes users and administrators precious time, effort, and resources.项目地址: https://gitcode.com/GitHub_Trending/ku/kubescape创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考