Aqwerty321/k8s-whisperer-agent

# K8sWhisperer K8sWhisperer 是一个为 PS1 DevOps x AI/ML 赛道构建的自主 Kubernetes 事件响应系统。它通过 LangGraph 工作流，将实时的集群症状转化为作用域明确、可解释的操作，该工作流能够观察集群状态、检测异常、诊断可能的原因、提出修复建议、应用安全策略、执行安全操作并记录所有结果。 该项目专为真实的 `minikube` 演示而设计，而非仅限模拟的原型。低爆炸半径的操作可以自动执行。高风险操作会暂停以等待 Slack 中的人工批准，并通过带有持久检查点状态的 FastAPI webhook 恢复执行。 实时的 Soroban 测试网合约 ID：`CBTXP7ZFNGAZ5TK5CRFKRJUHRKPOBESZ6PWD4CC4ZDNYPI774642LQSN` ## 问题陈述对齐 PS 需要一个端到端的事件响应循环： 1. 观察 2. 检测 3. 诊断 4. 规划 5. 安全门控 6. 执行 7. 解释与日志记录 K8sWhisperer 直接在 LangGraph 中实现了该循环，并使区块链工作与修复控制路径相互隔离，从而确保核心的评审演示保持稳定。 ## 核心能力 - 具备健康检查、运行时、事件、审计、Slack 回调以及认证端点的 FastAPI 后端 - 具有类型化共享状态和持久检查点恢复功能的 LangGraph 工作流 - 默认进行作用域限制在命名空间的 Kubernetes 观察和 Pod 级别的修复 - 带有签名请求验证和后台图谱恢复功能的 Slack 审批流 - 包含解释、决策、诊断证据和结果的持久化 JSONL 审计追踪 - 针对 `CrashLoopBackOff`、`OOMKilled` 和 `PendingPod` 的可重复演示辅助工具 - 针对 `ImagePullBackOff`、`CPUThrottling`、`EvictedPod`、`DeploymentStalled` 和可选 `NodeNotReady` 的额外异常覆盖 - 用于 Kubernetes、Slack 和 Prometheus 集成的类型化 MCP 服务器 - 用于在 Stellar 测试网上锚定已完成事件记录的可选 Soroban 认证流程 - 具备 Playwright 端到端覆盖率的首选桌面端认证仪表板 ## 已实现的事件路径 ### 核心评审路径 - `CrashLoopBackOff` 检测频繁重启的 Pod，收集日志和 describe 输出，规划 Pod 重启，仅在爆炸半径较低时自动批准，并验证恢复情况。 - `OOMKilled` 检测已终止的容器，在可用时使用工作负载资源上下文对其进行丰富，收集诊断证据，生成增加内存的建议，并通过 Slack 审批路由。启用工作负载补丁功能后，已批准的事件将对拥有的 `Deployment` 进行补丁操作，验证滚动更新，并显示修改前后的内存值。在默认的严格配置下，此操作仅保留为建议。 - `PendingPod` 检测至少保持 Pending 状态五分钟的 Pod，综合调度证据，并生成操作员指导，而不是进行不安全的变更。 ### 其他已实现的覆盖范围 - `ImagePullBackOff` 提取镜像和拉取上下文，并路由至操作员审查。 - `CPUThrottling` 当节流超过配置的阈值时，使用 Prometheus 指标推荐或可选修补 CPU 限制。 - `EvictedPod` 检测被驱逐的 Pod 并支持低爆炸半径的删除操作。 - `DeploymentStalled` 检测停滞的滚动更新并将其上报给人工处理。 - `NodeNotReady` 绝不修改节点的可选只读节点观察路径。 ## 架构 ### 工作流 1. `observe` 收集 Pod、Deployment、事件、可选节点以及可选的 Prometheus 指标快照。 2. `detect` 通过启发式基线加上保守的 LLM 丰富过程，生成具有严重性、目标资源、置信度和证据的类型化异常对象。 3. `diagnose` 拉取日志和 describe 样式的上下文，然后生成简短的根因总结。 4. `plan` 生成包含操作、目标、参数、置信度、爆炸半径和 HITL 要求的修复计划。 5. `safety_gate` 仅自动批准低爆炸半径、高于阈值且未在拒绝列表中的操作。 6. `execute` 或 `hitl` 立即执行安全操作，或暂停等待 Slack 批准并随后恢复。 7. `explain_log` 生成纯英文解释，更新 Slack，并追加持久的审计记录。 ### 运行时组件 - `backend/` FastAPI 应用程序、LangGraph 运行时、集成、MCP 服务器和认证逻辑。 - `k8s/` RBAC 清单、后端部署和演示工作负载。 - `scripts/` 集群设置、演示重置、部署、隧道、审批回退和 E2E 辅助工具。 - `contracts/incident-attestation/` 可选认证路径使用的 Soroban 智能合约。 - `frontend/` 用于浏览事件和验证认证的首选桌面端 React 操作员控制台。 - `tests/` 后端、运行时、Kubernetes、设置、认证和部署就绪测试。 ## 安全模型 - 自动修复仅限于高于配置的置信度阈值的低爆炸半径操作。 - 破坏性操作根据策略被列入拒绝名单。 - 人工批准是明确的，并且可以通过 Slack 恢复。 - 默认的 RBAC 仍限制在命名空间范围内，并避免使用 cluster-admin 权限。 - 可选的节点观察是只读的。 - Stellar 奖励路径不是修复控制循环的一部分。 ## 仓库布局 ``` backend/ FastAPI app, LangGraph workflow, integrations, MCP servers contracts/ Soroban smart contract for incident attestation docs/ Architecture, demo, rubric, and rehearsal notes frontend/ React attestation dashboard and Playwright tests k8s/ Backend manifests, RBAC, and demo workloads scripts/ Setup, deployment, demo, tunnel, and E2E helpers tests/ Automated backend and integration-oriented tests ``` ## 快速开始 ### 1. 安装 Python 依赖 ``` python3 -m venv .venv source .venv/bin/activate pip install -r requirements.txt ``` ### 2. 配置环境 - 如有需要，将 `.env.example` 复制为 `.env`。 - 提供 Slack 凭证、Gemini API 密钥和 Kubernetes 访问权限。 - 可选的观察设置： - `OBSERVE_ALL_NAMESPACES=true` - `OBSERVED_NAMESPACES=default,payments` - 可选的严格性和执行设置： - `ALLOW_WORKLOAD_PATCHES=false` - `ENABLE_NODE_READ_OBSERVATION=false` ### 3. 在本地运行 API ``` uvicorn backend.main:app --reload ``` 或者： ``` make run ``` ### 4. 验证健康状况 ``` curl http://127.0.0.1:8000/health ``` ### 5. 运行自动化后端测试 ``` make test ``` ## Minikube 部署 ### 准备演示集群 ``` make demo-setup make demo-deploy ``` ### 构建后端并将其部署到 minikube 中 ``` make deploy-backend ``` 这会在端口 `8010` 上部署 `Deployment/k8s-whisperer` 和 `Service/k8s-whisperer`。 ### 创建后端密钥 如果您需要在集群中使用实时的 Slack、Gemini 或 Stellar 值，请首先创建共享密钥： ``` bash scripts/sync_cluster_secrets.sh ``` 您也可以从 `k8s/backend-secret.template.yaml` 开始，在应用之前替换其中的占位符值。 当您的本地 `.env` 某个字段留空时，同步脚本会保留集群中现有的非空值，这可以防止意外丢失正在工作的 Slack 或 Soroban 配置。 ### 将集群内服务桥接到本地回调端口 ``` make public-bridge ``` 这使得公共回调路径保持指向稳定的本地端口，同时处理来自集群内后端的流量。 ## 演示工作流 ### 准备干净的评审就绪状态 ``` make demo-ready ``` ### 显示运行时快照 ``` make demo-snapshot ``` ### 填充主要演示场景 ``` bash scripts/demo_incident.sh crashloop | jq bash scripts/demo_incident.sh oomkill | jq bash scripts/demo_incident.sh pending | jq ``` ### 将 OOMKilled 演示重置为失败基线 ``` make demo-reset-oomkill ``` ### 清理旧的事件和审计干扰信息 ``` make demo-prune ``` ### 本地审批回退 ``` bash scripts/approve_incident.sh ``` 如果在排练期间 Slack 或公共回调路径不可用，请使用此方法。 ## 公共回调隧道 ### 临时隧道 ``` make tunnel ``` ### 稳定域隧道 参见 `docs/stable-domain-tunnel.md` 和 `scripts/tunnel_named.sh`。 ## API 接口 ### 运行时和事件 - `GET /health` - `GET /api/status` - `GET /api/incidents` - `GET /api/incidents/{incident_id}` - `GET /api/incidents/{incident_id}/summary` - `GET /api/incidents/{incident_id}/report` ### 审计和演示实用程序 - `GET /api/audit` - `GET /api/audit/{incident_id}` - `POST /api/incidents/run-once` - `POST /api/poller/run-once` - `POST /api/poller` - `POST /api/demo/prune` - `POST /api/demo/reset` ### Slack 和认证 - `POST /api/slack/actions` - `POST /api/attest` - `POST /api/attest/verify` ## MCP 服务器 直接从仓库运行类型化的 MCP 服务器： ``` make kubectl-mcp make slack-mcp make prometheus-mcp ``` Prometheus 奖励路径也可以由本地 Prometheus 实例支持： ``` make prometheus-up ``` ## 前端认证控制台 前端是一个首选桌面端的操作界面，用于浏览事件，通过后端认证 API 锚定事件记录，并在浏览器中使用 `stellar-sdk` 根据 Soroban 验证链上哈希。 ### 安装前端依赖 ``` npm --prefix frontend install ``` ### 在本地运行前端 ``` npm --prefix frontend run dev ``` ### 运行前端 E2E 覆盖率测试 ``` npm --prefix frontend run test:e2e ``` Playwright 套件使用 `scripts/run_frontend_e2e_stack.sh` 启动本地 Vite 应用，对集群内的后端进行端口转发，填充初始事件，并验证 UI 中的锚定及验证行为。 ## 可选的 Soroban 认证 区块链路径是一个可选的事后证明层。它不参与检测、诊断、规划、批准或执行过程。 ### 认证路径的功能 1. 从运行时或审计状态构建规范的事件记录。 2. 以稳定的格式对规范记录进行哈希处理。 3. 将哈希锚定在 Soroban 合约上。 4. 将交易 ID 持久化到运行时和审计状态中。 5. 根据后端计算的哈希验证链上值。 ### Soroban 设置 使用测试网进行开发。 1. 安装 Soroban CLI ``` cargo install --locked soroban-cli ``` 2. 创建本地身份 ``` soroban keys generate dev-admin soroban keys address dev-admin soroban keys secret dev-admin ``` 3. 为账户提供资金 ``` curl "https://friendbot.stellar.org/?addr=$(soroban keys address dev-admin)" ``` 4. 添加测试网网络 ``` soroban network add testnet \ --rpc-url https://soroban-testnet.stellar.org \ --network-passphrase "Test SDF Network ; September 2015" ``` 5. 构建合约 ``` rustup target add wasm32v1-none soroban contract build --manifest-path contracts/incident-attestation/Cargo.toml ``` 6. 部署合约 ``` soroban contract deploy \ --wasm contracts/incident-attestation/target/wasm32v1-none/release/incident_attestation.wasm \ --source dev-admin \ --network testnet ``` 7. 配置后端值 ``` STELLAR_NETWORK=testnet STELLAR_RPC_URL=https://soroban-testnet.stellar.org STELLAR_SECRET_KEY= STELLAR_CONTRACT_ID= ``` 8. 重新部署后端 ``` make deploy-backend ``` ### 经验证的认证流程 认证路径已经针对真实的 Soroban 测试网合约进行了验证： 1. 解决或填充初始事件。 2. 调用 `POST /api/attest`。 3. 确认返回了真实的交易 ID。 4. 通过前端浏览器流程或 `POST /api/attest/verify` 进行验证。 5. 确认链上哈希与规范的事件哈希匹配。 ### Web3 奖励提交清单 - 前端：`frontend/` - React 操作员控制台 - 位于 `frontend/src/lib/stellar.js` 的浏览器端 Stellar 集成 - 智能合约：`contracts/incident-attestation/` - 位于 `contracts/incident-attestation/src/lib.rs` 的 Soroban 合约源码 - 合约方法：`anchor(...)` 和 `get(...)` - 集成逻辑： - 位于 `backend/app/attestation/stellar.py` 的后端锚定/验证流程 - 位于 `backend/app/api/routes.py` 的认证 API - 位于 `frontend/src/lib/stellar.js` 的使用 `stellar-sdk/contract` 的前端验证路径 - 网络：Stellar 测试网 - 当前演示合约 ID：`CBTXP7ZFNGAZ5TK5CRFKRJUHRKPOBESZ6PWD4CC4ZDNYPI774642LQSN` - 端到端验证命令： ``` bash scripts/proof_soroban.sh ``` ## 文档 - `docs/architecture.md` - `docs/demo-runbook.md` - `docs/judge-demo.md` - `docs/judge-rehearsal-script.md` - `docs/rubric-mapping.md` - `docs/Langgraph_state_schema.md` ## 当前状态 ### 强势实现的功能 - 带有检查点暂停和恢复功能的核心 LangGraph 工作流 - 稳定的 `CrashLoopBackOff`、`OOMKilled` 和 `PendingPod` 演示案例 - 结合了启发式基线、经过验证的 LLM 丰富和可靠回退行为的混合异常检测 - Slack HITL 批准和审计日志 - 严格的默认安全姿态和 RBAC - 可选的 Prometheus 支持的 CPU 节流支持 - 可选的多命名空间观察 - 在启用补丁时，具有明确修改前后内存证据的感知 Deployment 的 `OOMKilled` 补丁生成 - 带有后端锚定和直接前端验证的可选 Soroban认证 - 具备 Playwright E2E 覆盖率的首选桌面端前端 ### 已知边界 - 为了演示的稳定性，检测有意以启发式为主导；LLM 路径是辅助性的、经过验证的，仅允许丰富或添加受支持的异常。 - 除非明确启用工作负载补丁，否则默认的 `OOMKilled` 路径仍仅保留为建议。 - `PendingPod`、`ImagePullBackOff`、`DeploymentStalled` 和 `NodeNotReady` 被有意设为非破坏性的指导或升级路径。 - 工作负载补丁支持仍然有限，主要针对 Deployment，而不是一个完全通用的工作负载修复引擎。 - 前端目前执行浏览器端直接合约读取以进行验证，但锚定仍通过后端运行，而不是钱包签名的浏览器交易流程。 - 审计日志是由文件支持的 JSONL，而不是由数据库支持的服务。 ## 许可证 本仓库当前未包含任何许可证文件。

标签：Agent, AIOps, AV绕过, CISA项目, CrashLoopBackOff, DLL 劫持, FastAPI, Human-in-the-loop, LangGraph, LLM, MCP, Minikube, NIDS, OOMKilled, Playwright, Python, Slack集成, Soroban, SRE, Stellar, Unmanaged PE, Webhook, 人机协同, 代理支持, 偏差过滤, 力导向图, 区块链, 告警, 大语言模型, 子域名变形, 子域名突变, 安全控制, 安全网关, 审计日志, 容器化, 异常检测, 故障诊断, 无后门, 根因分析, 模块化设计, 特征检测, 监控, 站点可靠性工程, 策略引擎, 网络安全挑战, 自动化修复, 自动化运维, 自定义请求头, 自愈系统, 运维自动化, 逆向工具