Wynn-hub/kubesentry

# KubeSentry 监控 English | [中文](README_zh.md) [](https://golang.org) [](LICENSE) [](https://hub.docker.com/r/wynnhub/kubesentry-webhook) [](https://hub.docker.com/r/wynnhub/kubesentry-operator) 一个 Kubernetes 验证准入 Webhook，用于强制执行以自定义资源定义形式定义的 OPA/Rego 策略，并配备一个 Operator 用于生命周期管理、版本控制和内置策略组。 ## 快速开始 ``` helm install kubesentry \ oci://registry-1.docker.io/wynnhub/kubesentry \ --namespace kubesentry-system \ --create-namespace ``` 无需登录 — 镜像和 Helm Chart 在 Docker Hub 上公开提供。Helm 预安装 Job 会自动生成 TLS 证书并修补 `ValidatingWebhookConfiguration`。 ## 架构 两个独立的 Go 二进制文件共享相同的自定义资源定义 API 类型： ``` ┌────────────────────────────────────────────────────────────────┐ │ Kubernetes Cluster │ │ │ │ ┌──────────────────┐ ┌────────────────────────────────┐ │ │ │ kubesentry- │ │ kubesentry-operator │ │ │ │ webhook │ │ │ │ │ │ │ │ PolicyGroupReconciler │ │ │ │ - OPA evaluator │ │ - creates child Policy CRDs │ │ │ │ - Policy cache │ │ - built-in library (37 rules) │ │ │ │ - /validate │ │ - conflict detection │ │ │ │ - /healthz │ │ │ │ │ │ - /readyz │ │ PolicyReconciler │ │ │ └────────┬─────────┘ │ - validates Rego │ │ │ │ │ - creates PolicyVersion │ │ │ │ watches │ - handles rollback │ │ │ ▼ │ │ │ │ ┌──────────────────┐ │ WebhookConfigReconciler │ │ │ │ Policy CRD │ │ - aggregates rules │ │ │ │ (cluster-scope)│ │ - patches VWC │ │ │ └──────────────────┘ └────────────────────────────────┘ │ │ │ │ ┌──────────────────┐ ┌────────────────────────────────┐ │ │ │ PolicyGroup CRD │ │ PolicyVersion CRD │ │ │ │ (cluster-scope) │ │ (immutable snapshots) │ │ │ └──────────────────┘ └────────────────────────────────┘ │ └────────────────────────────────────────────────────────────────┘ ``` ## 功能特性 - **OPA/Rego 策略引擎** — 直接内嵌 OPA，无需 sidecar - **基于 CRD 的策略** — 将策略定义为 `Policy` Kubernetes 资源 - **内置策略组** — 包含 37 条精选规则，涵盖安全性、效率和可靠性三个组，在安装时自动部署 - **策略分组** — 将策略组合在一起，支持按组和按策略的启用/禁用开关 - **自定义策略组** — 创建您自己的 `PolicyGroup` 自定义资源定义；当自定义策略与内置策略共享相同键时，自定义策略优先 - **结构化的违规消息** — 拒绝信息包含 `[group/key] message` 和描述字段；审计违规以 `AdmissionResponse.Warnings` 形式出现 - **执行模式** — `enforce` (阻止) 或 `audit` (仅记录日志 + 警告) - **版本控制** — 每次策略更改都会创建一个不可变的 `PolicyVersion` 快照 - **回滚** — 设置 `spec.rollbackTo.version` 可以恢复任何之前的版本 - **动态 Webhook 规则** — Operator 根据就绪的策略自动更新 `ValidatingWebhookConfiguration` - **自签名 TLS** — 在 Helm 安装期间通过预安装 Job 自动生成 - **并行评估** — 多个策略并发评估，超时时间为 5 秒 - **领导者选举** — Operator 以领导者选举方式运行以实现高可用 - **多平台** — 镜像支持 `linux/amd64` 和 `linux/arm64` ## 内置策略组 KubeSentry 包含 37 个内置策略，分为三个组，默认启用： ### 安全性 (23 个策略) | 键 | 默认模式 | 描述 | |---|---|---| | `runAsPrivileged` | enforce | 阻止以特权模式运行的容器 | | `privilegeEscalationAllowed` | enforce | 阻止 `allowPrivilegeEscalation: true` | | `runAsRootAllowed` | audit | 当未设置 `runAsNonRoot` 时发出警告 | | `notReadOnlyRootFilesystem` | audit | 当未设置 `readOnlyRootFilesystem` 时发出警告 | | `linuxHardening` | enforce | 要求至少满足以下之一：seccompProfile、seLinuxOptions、capabilities.drop | | `insecureCapabilities` | audit | 对不安全的能力添加发出警告 | | `dangerousCapabilities` | enforce | 阻止危险的能力 (SYS_ADMIN, NET_ADMIN, ...) | | `hostPIDSet` | enforce | 阻止 `hostPID: true` | | `hostIPCSet` | enforce | 阻止 `hostIPC: true` | | `hostNetworkSet` | audit | 当 `hostNetwork: true` 时发出警告 | | `hostPortSet` | audit | 当设置了 `hostPort` 时发出警告 | | `sensitiveContainerEnvVar` | enforce | 阻止名称匹配敏感模式的环境变量 | | `automountServiceAccountToken` | audit | 当自动挂载服务账户令牌时发出警告 | | `sensitiveConfigmapContent` | enforce | 阻止包含敏感内容键的 ConfigMaps | | `tlsSettingsMissing` | audit | 对没有 TLS 的 Ingress 发出警告 | | `clusterrolePodExecAttach` | enforce | 阻止授予 pods/exec 或 pods/attach 权限的 ClusterRoles | | `rolePodExecAttach` | enforce | 阻止授予 pods/exec 或 pods/attach 权限的 Roles | | `clusterrolebindingPodExecAttach` | enforce | 阻止按名称引用 exec/attach 角色的 ClusterRoleBindings | | `rolebindingRolePodExecAttach` | enforce | 阻止按名称引用 exec/attach 角色的 RoleBindings | | `rolebindingClusterRolePodExecAttach` | enforce | 阻止按名称引用 exec/attach ClusterRoles 的 RoleBindings | | `clusterrolebindingClusterAdmin` | enforce | 阻止绑定到 cluster-admin 的 ClusterRoleBindings | | `rolebindingClusterAdminClusterRole` | enforce | 阻止绑定到 cluster-admin ClusterRole 的 RoleBindings | | `rolebindingClusterAdminRole` | enforce | 阻止绑定到名为 cluster-admin 的 Roles 的 RoleBindings | ### 效率 (4 个策略) | 键 | 默认模式 | 描述 | |---|---|---| | `cpuRequestsMissing` | audit | 当未设置 CPU 请求时发出警告 | | `memoryRequestsMissing` | audit | 当未设置内存请求时发出警告 | | `cpuLimitsMissing` | audit | 当未设置 CPU 限制时发出警告 | | `memoryLimitsMissing` | audit | 当未设置内存限制时发出警告 | ### 可靠性 (10 个策略) | 键 | 默认模式 | 描述 | |---|---|---| | `readinessProbeMissing` | audit | 当缺少就绪探针时发出警告 | | `livenessProbeMissing` | audit | 当缺少存活探针时发出警告 | | `tagNotSpecified` | enforce | 阻止没有标签或使用 `:latest` 的镜像 | | `pullPolicyNotAlways` | audit | 当 imagePullPolicy 不是 Always 时发出警告 | | `priorityClassNotSet` | audit | 当未设置 priorityClassName 时发出警告 | | `deploymentMissingReplicas` | audit | 当 Deployment 副本数少于 2 时发出警告 | | `metadataAndInstanceMismatched` | audit | 当 `metadata.name` 和 `app.kubernetes.io/instance` 不一致时发出警告 | | `topologySpreadConstraint` | audit | 当未定义拓扑分散约束时发出警告 | | `hpaMaxAvailability` | audit | 当 HPA 的 maxReplicas ≤ minReplicas 时发出警告 | | `hpaMinAvailability` | audit | 当 HPA 的 minReplicas ≤ 1 时发出警告 | ### 自定义内置组 通过 Helm 值禁用整个组或单个策略： ``` builtinGroups: security: enabled: true policies: hostNetworkSet: enabled: false # disable this policy runAsRootAllowed: mode: enforce # override mode to enforce efficiency: enabled: false # disable the entire group ``` ## PolicyGroup 自定义资源定义 您还可以创建自己的组，混合使用内置和自定义策略： ``` apiVersion: kubesentry.io/v1alpha1 kind: PolicyGroup metadata: name: my-policies spec: enabled: true displayName: "My Custom Policies" policies: # use a built-in policy with mode override - key: runAsPrivileged mode: enforce # custom policy not in the built-in library - key: noDebugContainers mode: enforce rego: | package kubesentry deny[msg] { c := input.request.object.spec.containers[_] c.name == "debug" msg := "debug containers are not allowed" } match: operations: [CREATE, UPDATE] resources: - apiGroups: [""] apiVersions: ["v1"] resources: ["pods"] ``` 当 `PolicyGroup` 条目与现有的独立 `Policy` (即没有指向任何 `PolicyGroup` 的 `OwnerReference` 的策略) 共享相同的 `key` 时，独立策略具有更高优先级，组条目将被跳过。 ### 违规消息 当策略触发时，响应包含组、键和描述： ``` [security/runAsPrivileged] container "app" must not run as privileged 描述：Fails when securityContext.privileged is true. ``` `audit` 模式的违规以 `AdmissionResponse.Warnings` 形式出现 (请求被允许)。 ## PolicyException — 有时限、经审计的豁免 `PolicyException` 允许您绕过特定策略 (或整个 PolicyGroup，甚至所有策略) ，适用于一组有范围的资源，并在一段有限的时间内有效。 ### 快速示例 ``` apiVersion: kubesentry.io/v1alpha1 kind: PolicyException metadata: name: hr-system-legacy-migration spec: policyRefs: - run-as-privileged match: namespaces: [hr-system] duration: 24h reason: "Legacy billing migration; ticket OPS-1245" ``` ### 字段 - `policyRefs` / `policyGroupRefs` / `allPolicies` — 三者选一。选择特定策略、整个 PolicyGroup 或白名单所有策略。 - `match.namespaces` — 精确的命名空间名称 (无通配符)。 - `match.namespaceSelector` — `Namespace` 对象上的标签。 - `match.resourceSelector` — 被准入对象本身的标签。 - `duration` — 必填，Go `time.Duration` (例如 `24h`、`30m`)。 - `retainAfterExpiry` — 可选；默认 `0` (到期后立即删除)。 - `reason` — 必填，非空的审计字符串。 ### 规则 - 时间原点为 `metadata.creationTimestamp`。编辑 `duration` 会重新计算 `status.expiresAt`；`status.effectiveAt` 不会改变。 - `Expired` 是终态 — 曾经过期的异常对象无法通过编辑 `duration` 恢复。需创建新对象进行续期。 - 只有 `duration`、`retainAfterExpiry` 和 `reason` 是可变的。其他所有字段 (targets, match) 在创建时锁定。 - 不可变性通过 `ValidatingAdmissionPolicy` 强制执行，其 CEL 比较将列表字段 (`policyRefs`、`policyGroupRefs`、`match.namespaces`) 视为**有序**的。重新排序元素而不改变集合的补丁将被拒绝为违反不可变性。应用期间对 JSON 数组重新排序的工具应配置为保留原始顺序，或者您应该重新创建对象而不是修补。 ## 独立策略示例 ``` apiVersion: kubesentry.io/v1alpha1 kind: Policy metadata: name: deny-privileged spec: enforcementMode: enforce match: operations: [CREATE, UPDATE] resources: - apiGroups: [""] apiVersions: ["v1"] resources: ["pods"] rego: | package kubesentry deny[msg] { input.request.object.spec.containers[_].securityContext.privileged == true msg := "privileged containers are not allowed" } ``` 参见 [`examples/`](examples/) 获取更多即用型策略。 ### Pod 拦截 vs. Deployment 拦截 默认情况下，策略匹配 `pods`，这涵盖了所有工作负载类型。当应用 `Deployment` 时，`kubectl apply` 会立即成功 — Webhook 仅在 Deployment 控制器稍后尝试创建 Pod 时触发，因此拒绝会出现在 `kubectl describe deployment` 事件中，而不是在命令行上。 如果您希望对 Deployment 执行 `kubectl apply` 时立即失败，请将 `deployments` 添加到匹配规则**并**为每种资源类型编写单独的 Rego 规则，因为容器路径不同： | 资源 | Rego 中的容器路径 | |---|---| | `pods` | `input.request.object.spec.containers[_]` | | `deployments` | `input.request.object.spec.template.spec.containers[_]` | 同时拦截两者的策略示例 — 参见 [`examples/policy-no-privileged-with-deployments.yaml`](examples/policy-no-privileged-with-deployments.yaml)。 ## 回滚 设置 `spec.rollbackTo.version` — Operator 从目标 `PolicyVersion` 恢复 `spec.rego`、`spec.match` 和 `spec.enforcementMode`，并自动清除该字段： ``` apiVersion: kubesentry.io/v1alpha1 kind: Policy metadata: name: deny-privileged spec: rollbackTo: version: 2 ``` ## 安装 ### 前提条件 - Kubernetes 1.28+ - Helm 3.8+ - 已配置 `kubectl` ### 安装 (最新版) ``` helm install kubesentry \ oci://registry-1.docker.io/wynnhub/kubesentry \ --namespace kubesentry-system \ --create-namespace ``` ### 安装特定版本 ``` helm install kubesentry \ oci://registry-1.docker.io/wynnhub/kubesentry \ --version 1.0.1 \ --namespace kubesentry-system \ --create-namespace ``` ### 从源代码安装 ``` helm install kubesentry charts/kubesentry \ --namespace kubesentry-system \ --create-namespace ``` ### Docker Hub 镜像 | 镜像 | 标签 | |---|---| | [`wynnhub/kubesentry-webhook`](https://hub.docker.com/r/wynnhub/kubesentry-webhook) | `latest`, `v1.0.1`, `v1.0.0` | | [`wynnhub/kubesentry-operator`](https://hub.docker.com/r/wynnhub/kubesentry-operator) | `latest`, `v1.0.1`, `v1.0.0` | ## 配置 | 值 | 默认值 | 描述 | |---|---|---| | `webhook.replicas` | `2` | Webhook 服务器副本数 | | `webhook.image.tag` | *(chart 应用版本)* | 覆盖镜像标签 | | `operator.replicas` | `1` | Operator 副本数 | | `operator.image.tag` | *(chart 应用版本)* | 覆盖镜像标签 | | `tls.secretName` | `kubesentry-tls` | TLS Secret 名称 | | `failurePolicy` | `Fail` | Webhook 故障策略 | | `policy.versionHistoryLimit` | `20` | 每个策略的最大 `PolicyVersion` 对象数 | | `webhookNamespaceSelector` | 排除 `kube-system`, `kubesentry-system` | 命名空间选择器 | | `builtinGroups.security.enabled` | `true` | 启用安全策略组 | | `builtinGroups.efficiency.enabled` | `true` | 启用效率策略组 | | `builtinGroups.reliability.enabled` | `true` | 启用可靠性策略组 | | `builtinGroups..policies..enabled` | — | 启用/禁用单个内置策略 | | `builtinGroups..policies..mode` | — | 覆盖单个策略的模式 (`enforce`\|`audit`) | ## 开发 ### 要求 - Go 1.26+ - Docker (用于跨平台构建) - Helm 3.8+ ### 常用命令 ``` make test # run all tests make build # compile for local arch → bin/webhook, bin/operator make lint # go vet make helm-package # lint + package chart → dist/kubesentry-.tgz ``` ### 发布流水线 ``` # 首次：登录 Docker Hub docker login -u wynnhub helm registry login registry-1.docker.io -u wynnhub # 标记与发布 git tag v1.0.1 make release VERSION=v1.0.1 ``` `make release` 按顺序运行： | 步骤 | 命令 | 输出 | |---|---|---| | 1. 测试 | `go test ./...` | — | | 2. 交叉编译 | `docker run golang:1.26-alpine go build` | `bin/linux-amd64/`, `bin/linux-arm64/` | | 3. 推送镜像 | `docker buildx ... --push` | `wynnhub/kubesentry-webhook:v1.0.1` + `:latest` | | 4. 打包 Chart | `helm package` | `dist/kubesentry-1.0.1.tgz` | | 5. 推送 Chart | `helm push ... oci://` | `oci://registry-1.docker.io/wynnhub/kubesentry:1.0.1` | ### 多平台镜像 镜像以 OCI Manifest List 形式发布。Kubernetes 在拉取时会自动选择正确的平台 — 无需 Chart 配置。 ``` # 检查已发布平台 docker buildx imagetools inspect wynnhub/kubesentry-webhook:latest ``` ### 项目结构 ``` kubesentry/ ├── cmd/ │ ├── webhook/main.go # webhook server entrypoint │ └── operator/main.go # operator + tls-setup subcommand ├── internal/ │ ├── api/v1alpha1/ # CRD type definitions │ ├── builtins/ # embedded Rego library (37 built-in policies) │ │ └── rego/ # .rego files (one per policy) │ ├── webhook/ # OPA evaluator, cache, HTTP handler │ ├── operator/ # Policy, PolicyGroup, and WebhookConfig reconcilers │ └── tlssetup/ # ECDSA cert generation ├── charts/kubesentry/ # Helm chart │ ├── crds/ # CRD manifests (Policy, PolicyVersion, PolicyGroup) │ └── templates/ # K8s resource templates ├── Dockerfile.webhook # runtime-only, no build step └── Dockerfile.operator ``` ## 许可证 Apache License 2.0 — 详情参见 [LICENSE](LICENSE)。

标签：Docker, EVTX分析, Go语言, Groq API, Helm, OPA, pySHACL, RDFlib, Rego, 准入Webhook, 子域名突变, 安全可观测性, 安全合规, 安全策略, 安全防御评估, 提示词设计, 数据科学, 日志审计, 版本控制, 生命周期管理, 程序破解, 策略即代码, 策略组, 网络代理, 聊天机器人安全, 自动化策略, 自定义资源定义, 请求拦截, 资源治理, 资源验证, 集群治理, 靶场