protosaditya21/Kubesentinel

# Kubernetes 的 AI 工作负载安全 Kubernetes 负责保障代码的运行环境和消费内容。本项目是一个参考实现，旨在通过结合语义 sidecar 过滤、基于 Kubernetes Operator 的集群范围策略，以及使用 Tetragon/eBPF 的内核级可观测性，来防御 Agentic LLM 工作负载。 **状态：** 早期参考实现，尚未经过生产环境强化。欢迎贡献代码 —— 请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。 ## 概述 本仓库提供： - 一个 sidecar 组件（低延迟过滤 + 可插拔分类器）。 - 一个 Kubernetes Operator，定义了两个 CRD：`AIPolicy` 和 `SemanticBudget`。 - 一个准入 webhook，用于根据声明的 `AIPolicy` 规则验证 agent 清单。 - 一个运行时聚合器 endpoint，sidecar 使用它来报告高风险判定结果，operator 使用这些结果进行预算/隔离决策。 - 可选的 Tetragon/eBPF 追踪，用于将内核级事件与语义判定相关联。 请在 [docs/architecture.md](docs/architecture.md) 中阅读设计原理和边界说明。 ## 组件（查看重点） - **Sidecar**：`sidecar/` —— 一层（regex）和二层（classifier 接口）过滤。将高风险调用报告给 operator 的运行时 endpoint。 - **API 类型**：`api/v1alpha1/` —— `AIPolicy` 和 `SemanticBudget` 的 Go 类型（见 `api/v1alpha1/*.go`）。 - **Controllers**：`controllers/` —— `AIPolicyReconciler`、`SemanticBudgetReconciler` 和 `RuntimeAggregator`（见 `controllers/*.go`）。 - **Webhook**：`webhook/v1alpha1/` —— 在准入阶段根据 `AIPolicy` 约束对 agent 清单进行验证。 - **Tetragon**：`deploy/tetragon/` —— 示例 eBPF 追踪策略和用于提供内核级证据的基线清单。 - **Rego**：`policies/rego/` —— 消耗风险信号的示例确定性策略规则。 ## 快速开始（开发/测试） 前置条件：Kubernetes 1.27+，Helm 3，Docker/CRI 用于构建镜像。 在本地构建并部署 operator（minikube/kind）： ``` # 构建 sidecar（如果使用已发布的镜像，则为可选） cd sidecar && docker build -t /semantic-guardrail:dev . # 构建 operator 镜像 cd .. && docker build -t /ai-workload-controller:dev . # 应用 CRDs 和 RBAC kubectl apply -f config/crd/bases/ kubectl apply -f config/rbac/role.yaml # 安装 chart（或通过 'make run' 在本地运行 controller） helm install ai-workload-controller charts/ai-workload-controller -n ai-security --create-namespace ``` 部署示例 agent 和策略： ``` kubectl apply -f deploy/examples/agent-deployment.yaml kubectl apply -f config/samples/aipolicy_sample.yaml kubectl label namespace ai-agents ai-workload=true kubectl apply -f config/webhook/manifests.yaml ``` 验证步骤（健康/就绪状态、webhook 行为和预算模拟）请参见 [docs/deployment-guide.md](docs/deployment-guide.md)。 ## CRD 参考（概述） - `AIPolicy` (api/v1alpha1)： - `spec.identity` (string)：此策略适用的 Agent 身份。必填。 - `spec.allowedTools` (list)：允许 agent 调用的工具。 - `status.conditions`：`Accepted` 状态由 controller 设置；`status.quarantined` 由预算执行机制切换。 - `SemanticBudget` (api/v1alpha1)： - `spec.identity` (string)：身份或选择器范围。 - `spec.maxHighRiskActionsPerHour` (int)：预算阈值。 - `spec.quarantineOnBudgetExceeded` (bool)：超出预算时是否切换隔离标志。 - `status.WindowStart` / `status.CurrentHighRiskActions`：由 controller 和运行时聚合器管理。 Controller 行为（见 `controllers/`）： - `AIPolicyReconciler` 验证策略结构并设置 `Accepted` 状态；它不直接执行运行时行为（由 `webhook/` 和 sidecar 执行）。 - `SemanticBudgetReconciler` 管理每小时的时间窗口，并在超出预算时触发隔离操作。 - 运行时判定接收由运行时聚合器在 `/v1/verdicts` 暴露（见 `controllers/runtime_aggregator.go`）。 ## 示例 CR 针对支持 agent 的示例 `AIPolicy`（见 `config/samples/aipolicy_sample.yaml`）： ``` apiVersion: security.internal/v1alpha1 kind: AIPolicy metadata: name: support-agent-policy namespace: ai-agents spec: identity: support-agent allowedTools: - name: kb-search riskTier: low - name: ticket-update riskTier: medium requiresSyncCheck: true - name: billing-refund riskTier: high requiresSyncCheck: true maxCallsPerHour: 5 semanticBudget: maxHighRiskActionsPerHour: 10 quarantineOnBudgetExceeded: true ``` 独立 `SemanticBudget` 示例（见 `config/samples/semanticbudget_sample.yaml`）： ``` apiVersion: security.internal/v1alpha1 kind: SemanticBudget metadata: name: support-agent-budget namespace: ai-agents spec: identity: support-agent maxHighRiskActionsPerHour: 10 maxTotalActionsPerHour: 200 quarantineOnBudgetExceeded: true ``` ## 开发说明 - 在本地运行 controller 并带上调试标志：`go run ./main.go --metrics-bind-address=:8080 --health-probe-bind-address=:8081`。 - 当 `--enable-webhook` 为 true（默认）时，webhook 路径注册在 `/validate-agent-manifest`。 - 运行时聚合器监听 `:9443`（in-tree），用于接收来自 sidecar 的判定 POST 请求。 ## 值得关注的文件 - `main.go` — manager 设置，controller 注册，webhook 注册。 - `controllers/aipolicy_controller.go` — 策略验证和状态更新。 - `controllers/semanticbudget_controller.go` — 预算生命周期和隔离逻辑。 - `config/samples/aipolicy_sample.yaml` — 示例策略。 - `deploy/examples/agent-deployment.yaml` — 示例 agent + sidecar 连接配置。 ## 贡献 有关贡献指南和开发工作流，请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。 ## 许可证 Apache 2.0 — 见 [LICENSE](LICENSE)。

标签：AI安全, Chat Copilot, Docker镜像, EVTX分析, Sidecar, 子域名突变, 日志审计, 结构化提示词, 请求拦截