KamouloxPelvis/k-guard
GitHub: KamouloxPelvis/k-guard
K-Guard 是一个面向 K3s 集群的实验性 DevSecOps 安全治理平台，集成了容器漏洞扫描、零信任网络策略自动加固和 ChatOps 实时告警功能。
Stars: 2 | Forks: 0
⚠️ 警告：免责声明
*K-Guard 的设计符合行业安全标准，遵循 [](https://www.bestpractices.dev/projects/12124)。它已在 Cisco DevNet Code Exchange 平台上正式展示 [](https://developer.cisco.com/codeexchange/github/repo/KamouloxPelvis/K-Guard)*
*虽然安全性是核心优先事项，但本软件是作为个人和实验性的最小可行性产品（MVP）提供的。它被设计为探索 DevSecOps 安全架构的研究工具。作为一个不断演进的开源项目，K-Guard 将持续改进并由社区驱动强化。*
**K-Guard** 是一个用于 K3s 集群的安全治理与可观测性平台。它自动化了完整的安全生命周期：审计（**Trivy**）、网络修复（**Network Sentinel/Ansible**）以及 ChatOps 告警（**Cisco Webex**）。
## 📍 概述
* [🧪 技术栈](#en-tech-stack)
* [🚀 核心功能](#en-key-features)
* [📖 API 文档与参考](#en-api-documentation--reference)
* [🛠️ 安装与设置](#en-installation--setup)
* [1. CLI 安装程序](#en-1-cli-installer-go)
* [⚠️ CNI 建议](#en-network-isolation-recommendation)
* [2. 自动检查与依赖](#en-2-auto-check--dependencies)
* [3. 快速安装](#en-3-quick-start-procedure)
* [4. K-Guard 管理控制台 (SRE 运维)](#en-4-kguard-management-console)
* [5. 访问仪表板](#en-accessing-dashboard)
* [🛰️ Cisco Webex 集成](#en-cisco-webex-integration)
* [🛡️ Network Policy (Network Sentinel)](#en-network-policy--network-sentinel)
* [👤 联系方式与致谢](#en-contact--credits)
## 🧪 技术栈
* **后端**：FastAPI (Python), Ansible Core, Trivy。
* **前端**：Vue.js 3, Tailwind CSS, Fetch, JWT 认证。
* **安装程序**：Go (Bubble Tea / Lipgloss)。
* **创建环境**：Ubuntu 24.04 LTS, K3s, Kamatera VPS。
## 🚀 核心功能
* **Trivy 安全引擎**：直接从 UI 扫描容器镜像中的漏洞。
* **Network Sentinel**：通过 Ansible playbook 实现幂等的零信任 NetworkPolicies。
* **Cisco Webex ChatOps**：实时事件告警，并在 SQLite 中保留集成设置。
* **SRE 控制中心**：实时监控集群延迟、存储诊断和 pod 健康状况。
## 📖 API 文档与参考
K-Guard 使用 **Swagger UI (OpenAPI 3.1)** 自动生成交互式 API 文档。这允许开发者和安全审计员直接从浏览器探索和测试所有 endpoint。
- **交互式 UI：** `https:///docs`
- **已记录的功能：** - 🔍 K3s 基础设施指标
- 🔐 认证与 token 管理
- 💓 系统健康检查 (Liveness Probes)
## 🛠️ 安装与设置
### 1. CLI 安装程序
通过专用的 **Go** 安装程序进行全栈部署：
* 检查系统依赖和 Docker socket 可访问性。
* 使用 `bcrypt` 处理安全的凭据哈希。
* 将 secret 同步到 K3s 并部署核心 manifest。
### ⚠️ *网络隔离建议 (CNI)*
*为了通过 Network Policies 确保严格的微隔离，实施高级 CNI（Calico、Cilium、Kube-router）至关重要。使用默认的 Flannel CNI 可以保持应用程序正常运行，但集群将忽略东西向（pod 间）过滤规则*。
### 2. 自动检查与依赖
助手会启动一个“飞行前检查”脚本，以验证 Docker 和 K3s API 的安全配置。主机前置条件：
* K3s (`curl -sfL https://get.k3s.io | sh -`)。
* Docker (`sudo apt install docker.io -y`)。
* Python 3 & Pip。
### 3. 快速安装流程
```
# 克隆 repository
git clone [https://gitlab.com/portfolio-kamal-guidadou/k-guard.git](https://gitlab.com/portfolio-kamal-guidadou/k-guard.git)
cd installer (k-guard/installer)
# 授予执行权限
chmod +x install-kguard
# 启动安装并按照向导操作
./kguard-install or sudo ./kguard-install
```
### 4. K-Guard 管理控制台 (SRE 运维)
为了符合专业的 **SRE（站点可靠性工程）** 标准，K-Guard 部署了一个全局管理命令。这允许管理员直接从 VPS 终端监控和管理基础设施的健康状况，而无需在复杂的目录结构中导航。
| 命令 | 描述 | 场景 |
| :--- | :--- | :--- |
| **`kguard`** | **主要入口点：启动或验证 K-Guard 服务。** | **全局访问** |
| `kguard status` | 显示 Systemd 服务和 K3s 连接的实时状态。 | 运维健康状况 |
| `sudo kguard logs` | 流式传输实时后端日志，包括安全审计和 API 命中。 | 故障排除 |
| `kguard k8s` | 快速访问 `k-guard` namespace 内的 Kubernetes 资源诊断。 | 集群管理 |
**示例：实时监控与控制**
```
# 启动管理快捷方式
kguard
# 实时监控安全事件
sudo kguard logs
```
### 5. 访问仪表板
在您的 K3s 集群上完成部署后，K-Guard 界面将通过安全的 endpoint 公开。
1. **URL**：打开浏览器并导航至 `http://VPS_IP:8445`（或在本地 `/etc/hosts` 中配置的主机名加上您的 VPS IP 地址，例如：http://k-guard.local:8445），或任何您想要用来访问的名称。
2. **认证**：使用安装过程中定义的管理员凭据登录，并访问实时的 Sentinel 拓扑和安全扫描。
## 🛰️ Cisco Webex 集成
将技术安全审计转化为实时运营告警：
1. **启用**：直接在 **设置 (Settings)** 面板中切换 Webex 通知器。
2. **配置**：输入您的 `Bot Access Token` 和 `Target Room ID`。
3. **验证**：只有在连接测试成功后，设置才会持久化保存在 `kguard.db` SQLite 数据库中。
## 🛡️ Network Policy (Network Sentinel)
K-Guard 通过利用由 **Ansible Core** 驱动的自动化、幂等修复引擎，强制执行**零信任**安全态势。
### ⚙️ 强化引擎 (`harden_policies.yml`)
“Network Sentinel”的核心是一个复杂的 Ansible playbook，用于编排集群安全生命周期：
* **自动发现**：动态扫描集群以识别活动的 namespace 和运行中的工作负载（不包括关键的系统 namespace）。
* **端口映射**：自动从运行中的 pod 中提取容器端口，以确保在强化过程中合法流量永远不会被中断。
* **幂等部署**：使用 `kubernetes.core.k8s` 模块确保安全状态始终与所需策略保持一致，防止配置漂移。
### 📄 动态模板 (Jinja2)
K-Guard 利用 **Jinja2 模板** 动态生成上下文感知的安全规则：
* **`core_baseline.j2`**：实现“默认拒绝”基础（Ingress/Egress 隔离）。
* **`app_internal_bridge.j2`**：自动将 Ingress Controller 链接到发现的应用端口。
* **`app_egress.j2`**：使用 CIDR 和端口过滤，为特定服务（例如 MongoDB Atlas, Cisco Webex API）提供强化的出站规则。
* **`audit_exception.j2`**：安全的“诊断通道”，允许 K-Guard Sentinel 执行健康检查而不影响整体的零信任态势。
### 🚀 UI 驱动的修复 (设置)
通过设置面板中的 **“部署强化”** 功能，用户可以一键触发 Ansible 引擎。这弥合了高级安全意图与底层 YAML 执行之间的差距：
* **可视化拓扑**：实时识别脆弱或隔离的节点。
* **一键强化**：立即将整套 Ansible 驱动的安全套件应用到集群。
* **诊断 Sentinel**：集成的连接审计，以验证策略有效且不会造成破坏。
## 👤 联系方式与致谢
© 2026 - **Kamal Guidadou** *DevSecOps, SRE 与云安全*
* 🌐 **作品集**：[https://portfolio.devopsnotes.org](https://portfolio.devopsnotes.org)
* ✍️ **技术博客**：[https://blog.devopsnotes.org](https://blog.devopsnotes.org)
标签：AV绕过, DevSecOps, FastAPI, K3s, NetDevOps, Vue.js, 上游代理, 安全合规, 日志审计, 系统提示词, 网络代理, 自动化运维, 逆向工具