Kekechi/homelab-proxmox-harness

# homelab-proxmox-harness 一个基于 Proxmox VE 构建的私有云安全平台。该技术栈涵盖基础设施即代码、双层内部 PKI、支持加密传输的权威 DNS、构件供应链镜像、集中式日志聚合以及 Splunk SIEM —— 它们作为一个信任链被串联在一起，其中每一层都依赖于其下一层。 运营工作由基于 Claude Code 构建的**人类在环 AI pipeline**（Planner → Generator → Evaluator）处理，并在 AI 自身上建立了一个形式化建模的安全边界：网络隔离、IAM 范围限制和基于 hook 的强制执行 —— 应用于基础设施的安全工程原则同样适用于操作它的 agent。 **三大支柱：** 安全基础设施 · 基础设施即代码 · AI 辅助运营 ## 平台架构 每个服务层仅依赖于信任链中位于其下方的层： ``` ┌──────────────────────────────────────────────────────┐ │ AI Operations Layer │ │ PGE Pipeline (plan → generate → review → apply) │ │ Squid proxy isolation · IAM scoping · Hook gates │ └──────────────────┬───────────────────────────────────┘ │ provisions & configures ┌──────────────────▼───────────────────────────────────┐ │ Compute │ │ Proxmox VE · Terraform (bpg/proxmox) · Ansible │ │ MinIO (S3 state) · sandbox + production isolation │ └──────────────────┬───────────────────────────────────┘ │ base trust for all services ┌──────────────────▼───────────────────────────────────┐ │ PKI (step-ca, two-tier) │ │ Offline root CA VM + Always-on issuing CA (ACME) │ │ All services receive TLS certs from internal CA │ └──────────────────┬───────────────────────────────────┘ │ resolves internal services ┌──────────────────▼───────────────────────────────────┐ │ DNS (PowerDNS Auth + Recursor + DNSdist) │ │ Authoritative · Recursive · DoT/DoH-ready │ │ Per-host DNS query telemetry via dns-collector │ └──────────────────┬───────────────────────────────────┘ │ serves packages to all deployments ┌──────────────────▼───────────────────────────────────┐ │ Artifact Supply Chain (Nexus CE) │ │ APT proxy · OCI registry · Terraform provider mirror │ │ Offline-capable: no internet dependency post-setup │ └──────────────────┬───────────────────────────────────┘ │ receives syslog from all layers ┌──────────────────▼───────────────────────────────────┐ │ Observability │ │ OTel Collector Contrib gateway (all managed hosts) │ │ MinIO S3 archive + Splunk HEC exporter │ └──────────────────┬───────────────────────────────────┘ │ detection + AI analysis ┌──────────────────▼───────────────────────────────────┐ │ SIEM (Splunk Enterprise) │ │ HEC ingest · AI Toolkit · MCP Server integration │ │ DNS query logs · auth events · Proxmox API audit │ └──────────────────────────────────────────────────────┘ ``` ## 已构建内容 ### 基础设施底座 - **Terraform (bpg/proxmox v0.99+)** — 通过三个可重用模块配置 Proxmox 虚拟机 (VM) 和 LXC：`proxmox-vm` (cloud-init)、`proxmox-lxc` (非特权 Debian 容器)、`proxmox-network` (Linux 网桥) - **Ansible (13 个角色)** — 配置所有已开通的主机；角色具备幂等性，且来源于供应商仓库（非发行版软件包） - **MinIO** — 自托管的 S3 用于 Terraform 远程状态；每个环境配有独立的存储桶以及受限范围的 IAM 密钥 - **集中式配置** — `config/.yml` 是唯一事实来源；`make configure` 从一个文件中生成 tfvars、Ansible inventory、Squid 白名单和 `.envrc` - **两个环境** — 沙盒和生产环境具有物理隔离的凭证；生产环境的部署在设计上被禁止（生产令牌永远不会出现在开发容器中） 每个服务都通过 Terraform 的特性标志（`enable_pki`、`enable_dns` 等）进行部署控制，允许分阶段推出和干净的拆除。 ### PKI — 双层内部 CA - **离线根 CA**（VM，按需启动）：使用 step-cli 生成自签名根证书；除签名操作期间外，其余时间均保持关机状态 - **签发 CA**（始终在线的 LXC）：运行带有 ACME + JWK provisioner 的 step-ca；为 DNS、Nexus、Splunk 和 Ansible 管理的 TLS endpoint 签发证书 - 根证书通过 `common` Ansible 角色分发到系统信任库 —— 新主机开箱即信任内部服务 - 专为 ACME 自动续期而设计；无需手动管理证书 ### DNS — 完整解析器栈 - **PowerDNS Authoritative** (SQLite/WAL 后端，仅限回环) — 管理内部区域；通过 API 密钥进行身份验证 - **PowerDNS Recursor** — 递归解析器；内部区域转发给 Auth，其余所有请求转发至上游 - **DNSdist** — 面向客户端的前端；普通 DNS 端口 53，DoT 端口 853，DoH 端口 443（通过 step-ca ACME 进行 TLS）；受 ACL 控制的查询源 - **dns-collector** (dmachard/dns-collector) — 按主机部署的轻量级查询探针；通过 syslog 将 DNS 遥测数据转发至 OTel Collector；在 Splunk 中提供按主机划分的 DNS 可见性 ### 构件供应链 — Nexus CE - APT 代理镜像了 Debian 软件包仓库 —— 所有 Ansible 部署均通过 Nexus 安装软件包；在引导启动后，任何受管主机都不需要直接的互联网访问 - 用于容器镜像的 OCI 注册表 - Terraform provider 注册表 —— 离线锁定 provider 版本 - 用于自定义构件（例如 Splunk 应用包、自定义二进制文件）的 Raw 托管仓库 - 带有来自内部 CA 的 TLS 的 nginx 反向代理 ### 可观测性 — OTel Collector 网关 - **otelcol-contrib** 作为中央日志网关部署；在端口 1514 上接收来自所有受管主机的 syslog (RFC 5424, TCP) - Memory limiter + batch processor + resourcedetection 处理器 - 双重导出：MinIO S3 存储桶（`otelcol-logs`，365 天生命周期）用于长期归档，Splunk HEC 用于实时 SIEM 摄取 - 日志来源：DNS 查询日志 (dns-collector)、主机身份验证事件 (rsyslog)、Proxmox API 审计日志、OPNsense 防火墙日志 ### SIEM — Splunk Enterprise - 单实例 Splunk Enterprise（Ubuntu 24.04，大小按 Splunk 最低要求配置） - 通过 HEC 令牌身份验证从 OTel Collector 摄取 - 配置了 RBAC：拥有 `mcp_tool_execute` 能力的专用 MCP Server 用户，仅限 AI 工具包操作 - 安装了 Splunk AI Toolkit 和 MCP Server —— 支持 AI 辅助搜索和检测规则编写 - Splunk MCP Server 使 Claude Code 能够在检测工程会话期间直接查询 Splunk ## AI 运营 Harness ### Planner-Generator-Evaluator (PGE) 架构 基础设施变更通过三个特定用途的 agent 角色推进，并在每个阶段之间设有人工审批闸门： | 角色 | 模型 | 职责 | |---|---|---| | **iac-planner** | Claude Opus | 阅读现有代码和文档，研究变更，生成结构化计划 —— 不编写任何代码 | | **iac-generator** | Claude Sonnet | 将*已批准*的计划转换为 Terraform/Ansible 代码 —— 不进行计划或审查 | | **tf-reviewer** | Claude Sonnet | 审查生成的代码的安全性、正确性以及 bpg/proxmox 规范 —— 返回 `APPROVE` / `WARN` / `BLOCK` | 任何 agent 都不能跳过闸门或授予自己继续执行的权限。操作员在生成代码之前批准计划；操作员在任何 apply 运行之前审查裁决结果。 ### AI 的安全边界 应用于基础设施的工程纪律同样适用于操作它的 agent： | 控制 | 机制 | 防止事项 | |---|---|---| | **网络隔离** | 开发容器位于 `internal:true` Docker 网络上；所有流量均通过 Squid 正向代理（白名单：沙盒 VLAN、MinIO、GitHub releases、Terraform 注册表） | Claude 访问生产基础设施或任意互联网 | | **IAM 范围限制** | Proxmox 令牌 ACL 仅限 `/pool/sandbox`；MinIO 密钥仅限 `tfstate-sandbox` 存储桶；`privsep=1` 阻止特权提升 | Claude 影响生产状态或 Proxmox IAM | | **PreToolUse hooks** | 在执行前阻止 `terraform destroy`、`state rm`、`force-unlock` —— 独立于任何 Claude 指令 | 意外或被注入的破坏性操作 | | **凭证隔离** | 生产 Proxmox 令牌永远不会配置在开发容器中 | 即使所有其他控制都被绕过，生产部署也会在身份验证阶段失败 | 完整分析请见 [`docs/threat-model.md`](docs/threat-model.md) —— 包括模型*未能*防护的内容以及残余风险。 ### 技能 (斜杠命令) | 命令 | 功能 | |---|---| | `/design ` | 在规划之前探索架构决策 —— 每次一个决策，不涉及代码 | | `/infra-plan ` | 通过 iac-planner (Opus) 进行结构化基础设施规划 | | `/generate` | 通过 iac-generator 从已批准的计划编写 Terraform/Ansible | | `/review [files]` | 通过 tf-reviewer 进行单次代码审查 —— `APPROVE` / `WARN` / `BLOCK` | | `/polish [code\|plan\|design]` | 迭代审查-修复循环直到 `APPROVE` —— 所有循环均在 subagent 中运行 | | `/tf-deploy ` | 完整的 Terraform pipeline：设计 → 规划 → 生成 → 审查 → apply | | `/ansible-deploy ` | 完整的 Ansible pipeline：设计 → 规划 → 生成 → 审查 → 运行 | | `/ansible-run` | 针对已审查的 Ansible 代码执行预检 + 运行 + 验证 | | `/assess ` | 结构化项目评估 —— 在修复前显现隐藏假设 | | `/handoff` | 打包生产计划以供操作员交接 | | `/retro` | 会话回顾 —— 总结提示工程教训和技能生命周期 | ## 检测工程 可观测性栈旨在生成编写和验证检测规则所需的信号： - **DNS 查询遥测** — 每台主机上的 dns-collector 通过 OTel 将所有查询馈送到 Splunk；可以检测异常查询模式、C2 信标特征和 DNS 数据外传企图 - **身份验证事件日志记录** — 受管主机上的 rsyslog 将身份验证事件（SSH 登录、sudo、PAM）馈送到 OTel Collector - **Proxmox API 审计追踪** — API 请求日志显现意外的资源创建、令牌使用异常和横向移动企图 - **防火墙日志** — OPNsense 将 syslog 转发到 OTel Collector；提供跨 VLAN 的网络级可见性 **攻击模拟**（积极开发中）：自动化脚本针对摄取的特定数据源 —— DNS 查询、身份验证事件、API 调用 —— 生成已知的恶意模式。检测规则在部署到生产环境之前会针对模拟攻击进行验证。 **Splunk AI Toolkit + MCP Server** — Claude Code 可以在检测会话期间直接查询 Splunk，将日志源进行关联，并在与基础设施变更相同的对话中迭代 SPL 查询。 ## 快速开始 要求：Proxmox VE 8.x、Docker + Dev Containers、direnv。 ``` git clone && cd homelab-proxmox-harness cp config/sandbox.yml.example config/sandbox.yml # 编辑 config/sandbox.yml — Proxmox 节点、网络 CIDR、service flags make configure # generates tfvars, inventory, Squid allowlist, .envrc # 填写 .envrc：Proxmox token、MinIO keys（参见 docs/proxmox-iam.md） direnv allow make build # rebuild Squid image with updated allowlist # 在 dev container 中重新打开（VS Code：Ctrl+Shift+P → “Dev Containers: Reopen in Container”） make verify-isolation # confirm network isolation make init && make plan # initialize state backend, plan infrastructure make apply # apply plan file ``` 完整指南：[`docs/guides/deployment-guide.md`](docs/guides/deployment-guide.md) ## 文档 **设计记录** — 来自架构会议的决策日志，记录了决定了什么以及为什么： | 文档 | 主题 | |---|---| | [`dns-design.md`](docs/design/dns-design.md) | PowerDNS 栈架构 | | [`otelcol-design.md`](docs/design/otelcol-design.md) | OTel Collector 网关 | | [`artifact-server-design.md`](docs/design/artifact-server-design.md) | Nexus CE 选择与布局 | | [`splunk-hackathon-design.md`](docs/design/splunk-hackathon-design.md) | Splunk AI Toolkit 集成 | | [`dns-log-pipeline.md`](docs/design/dns-log-pipeline.md) | DNS 遥测 pipeline | | [`mgmt-vlan-design.md`](docs/design/mgmt-vlan-design.md) | 管理 VLAN 分段 | | *(以及 `docs/design/` 中的另外 9 个)* | | **运营指南：** | 文档 | 内容 | |---|---| | [`deployment-guide.md`](docs/guides/deployment-guide.md) | 分阶段沙盒部署（5 个阶段） | | [`pki-setup.md`](docs/guides/pki-setup.md) | 双层 CA 初始化和证书生命周期 | | [`splunk-setup.md`](docs/guides/splunk-setup.md) | Splunk Enterprise 与 OTel 的连接 | | [`trust-root-ca.md`](docs/guides/trust-root-ca.md) | 在工作站上安装内部根 CA | | [`minio-setup.md`](docs/guides/minio-setup.md) | MinIO 引导与存储桶 IAM | **架构文档：** - [`docs/proxmox-iam.md`](docs/proxmox-iam.md) — API 令牌设计、ACL 路径、角色定义 - [`docs/threat-model.md`](docs/threat-model.md) — 隔离模型：覆盖范围、未覆盖范围、残余风险 - [`docs/network-policy.md`](docs/network-policy.md) — Squid 白名单、SSH 隧道架构 ## 路线图 截至 2026 年夏季的积极开发优先事项： 1. **检测工程** — 从受管主机摄取防火墙日志和身份验证 syslog；针对 DNS、网络和身份验证数据源的检测规则；用于规则验证的攻击模拟脚本 2. **AI-Agent 滥用防御** — 强化 PreToolUse hook 覆盖范围，审计 agent 工具范围，并记录针对 PGE harness 的对抗性测试用例 3. **Splunk 黑客松** — 将 OTel → Splunk pipeline、AI Toolkit 集成和检测规则集打包作为黑客松参赛的可复现参考架构 4. **管理 VLAN** — 将 DNS、PKI、MinIO 和管理接口隔离到具有严格出入站策略的专用网段上 更远的规划：Keycloak (OIDC/SSO)、GitLab (自托管 CI/CD + GitOps)、Prometheus + Grafana、Wazuh EDR、DNSSEC + RPZ 威胁情报黑名单。请见 [`docs/v.md`](docs/vision.md)。 ## 许可证 MIT

标签：AI辅助运维, Proxmox, 安全基础设施, 安全运营, 扫描框架, 智能代码审计, 私有云平台, 系统提示词, 请求拦截