raajsivaram/triad-sentinel
GitHub: raajsivaram/triad-sentinel
基于 Google ADK 构建的多 Agent AI 系统，自动审计 GCP 云架构、IaC 及 SOW 文档在安全、SRE 和 FinOps 三大维度的合规性。
Stars: 0 | Forks: 0
# 🛡️ Triad Sentinel
**一个面向 Google Cloud Platform (GCP) 的企业级 AI 架构审查委员会**
Triad Sentinel 是一个企业级的多 Agent AI 系统，旨在自动审计云架构蓝图、基础设施即代码 模板、Mermaid 图表和工作说明书 (SOW) 文档。它根据三大核心支柱对设计进行评估：**安全合规**、**站点可靠性工程 (SRE) 基线**以及 **FinOps (成本优化)**。
该系统使用 **Google Agent Development Kit (ADK)** 构建并以 **Vertex AI Agent Engine** 为目标平台，实施了严格的深度防御护栏、运行前密钥拦截、LLM 注入预防以及多 Agent 共识路由。
## 🏢 系统架构与工作流
系统被结构化为一个有向图工作流，在主管编译网关的编排下进行并行专家审查，并封装在可视化的 Chainlit UI 中。
```
graph TD
UI[Chainlit UI / API Client] -->|Raw Text / .docx / .mmd| API[FastAPI Ingress]
subgraph Defense-in-Depth Guardrails
API --> G1[1. Secret Masker]
G1 -->|Clean| G2[2. Scope & Intent Validator]
G2 -->|Valid| G3[3. Injection & Bypass Detector]
G3 -->|Safe| G4[4. Plan-Phase Security Gate]
end
G4 --> Sup[Architecture Supervisor]
Sup -->|Tool Call| MP[Mermaid Parser]
Sup -->|Tool Call| PP[Plan Parser]
Sup -->|Tool Call| STRIDE[STRIDE Analyzer]
Sup -->|Route| SEC[Security Compliance Specialist]
Sup -->|Route| SRE[SRE & FinOps Specialist]
subgraph MCP ["Model Context Protocol (MCP)"]
SEC -->|Fetch| P1[(zero_trust_iam.md)]
SEC -->|Fetch| P2[(finops_baselines.md)]
SRE -->|Fetch| P3[(ha_compute_rules.md)]
SRE -->|Fetch| P2
end
SEC --> Report[Executive Sign-Off Report]
SRE --> Report
Sup --> Report
Report --> UI
```
## 🛡️ 深度防御安全护栏
在任何请求到达 LLM 之前，都必须经过四个严格的、程序化的 Python 护栏，以确保企业安全性和计算效率：
1. **接入阶段：密钥掩盖护栏 (`src/guardrails/secret_masker.py`)**
* **逻辑：** 拦截传入请求并扫描高风险的暴露模式（AWS 密钥、GCP Service Account JSON、RSA 私钥）。
* **动作：** 立即终止执行并返回 HTTP 400 `SECRET_EXPOSURE` 错误，防止凭证进入 LLM 上下文或 Cloud Logging。
2. **领域锁定：范围与意图验证器 (`src/guardrails/scope_validator.py`)**
* **逻辑：** 一种轻量级的、基于规则的启发式检查，确保输入包含架构上下文（IaC、Mermaid、GCP、SOW）。
* **动作：** 在 API 层以 HTTP 400 `SCOPE_VIOLATION` 阻断闲聊、天气查询或一般知识问题，从而节省 LLM 计算成本。
3. **LLM 安全：注入与绕过检测器 (`src/guardrails/injection_detector.py`)**
* **逻辑：** 检测直接 prompt 注入、越狱尝试（"ignore previous instructions"）以及过程绕过（"skip the security review"）。
* **动作：** 以 HTTP 400 `SECURITY_BLOCK` 错误阻断恶意意图。
4. **规划阶段：本地安全网关 (`src/agents/supervisor.py`)**
* **逻辑：** 在调用下游工具之前执行的回调钩子。它解析候选路径和文件格式。
* **动作：** 通过抛出 `ValueError` 来阻止未经授权的目录遍历并拒绝不允许的配置格式。
## 🤖 多 Agent 编排与工具
该平台使用三个高度专业化的 Agent 协同工作，并配备了自定义的程序化技能：
* **高级企业架构主管：** 编排工作流，并行路由任务，并综合生成最终的高管仪表板。
* **安全合规专家：** 利用 MCP 根据 Zero-Trust 基线验证身份控制、网络边界和数据加密。
* **SRE 与 FinOps 专家：** 识别单点故障 (SPOF)、自动扩缩容缺口、可观测性需求以及 GCP 成本低效问题。
### 🛠️ 自定义 Agent 技能
* **Mermaid 解析器 (`parse_mermaid_architecture`)：** 将来自可视化 Mermaid 图表的节点、连接和信任边界提取为结构化的 JSON。
* **计划解析器 (`parse_infrastructure_plan`)：** 将原始 IaC (Terraform/HCL/YAML) 或 SOW 文档解析为结构化的组件块。
* **STRIDE 分析器 (`analyze_stride`)：** 对 11 种组件类型（Compute、K8s、Serverless、CDN、Network 等）执行深度威胁建模，将风险映射到身份假冒、篡改、抵赖、信息泄露、拒绝服务 和权限提升。
## 🔌 模型上下文协议 (MCP) 集成
* **资源 URI 方案：** 使用 `policy://[filename]` 动态呈现 markdown 文档。
* **GCP 原生策略：**
* `zero_trust_iam.md`：GCP IAM、VPC Service Controls 和 Cloud KMS 基线。
* `ha_compute_rules.md`：Regional MIGs、Cloud Spanner 和 Cloud Monitoring 基线。
* `finops_baselines.md`：GCE right-sizing、GCS lifecycle rules 和 Spot VM 强制要求。
## 🎨 “Vibe” UI
Triad Sentinel 具有一个 **Chainlit** 前端，可实时可视化多 Agent 编排。UI 显示可折叠的 "Steps"，准确展示密钥掩盖器何时触发、MCP 服务器何时获取策略，以及并行专家何时完成审计。它还原生支持通过聊天界面直接上传 `.docx`（SOW 文档）和 `.mmd`（Mermaid 图表）。
## 🚀 SRE CI/CD 自动化
在 `.github/workflows/deploy.yml` 中配置了一个成熟的、可用于生产的 GitHub Actions 流水线：
* **解耦的 CI/CD：** 每次推送都会运行自动化测试 (`pytest`)。部署到 Vertex AI Agent Engine 的操作严格受手动 `workflow_dispatch` 触发器控制，以防止产生不必要的云计算成本。
* **Zero-Trust 认证：** 使用现代 OpenID Connect (OIDC) / Workload Identity Federation 连接到 Google Cloud，消除了长期有效的静态 Service Account 密钥。
## 🏃 如何运行
### 前置条件
```
pip install -r requirements.txt
```
### 启动应用
打开两个终端窗口。
**终端 1 — 启动 FastAPI 后端：**
```
.\.venv\Scripts\python.exe -m uvicorn src.main:app --port 8000
```
**终端 2 — 启动 Chainlit UI：**
```
.\.venv\Scripts\chainlit run src/ui/chainlit_app.py --port 8080
```
然后在浏览器中打开 `http://localhost:8080`。
## 🧪 验证与测试套件
`tests/test_agents.py` 中的测试套件涵盖了所有核心安全规则并能顺利执行。
* **密钥掩盖护栏：** 断言在暴露密钥时提前终止并返回结构化的错误块。
* **范围与注入护栏：** 断言在闲聊和越狱尝试时返回 HTTP 400 阻断。
* **计划阶段网关拦截：** 断言在目录遍历和不允许的 XML 格式下抛出 `ValueError`。
* **API Endpoint 集成：** 使用 FastAPI `TestClient` 断言正确的状态码和 JSON 输出。
**执行命令：**
```
.\.venv\Scripts\pytest.exe tests/
```
标签：DevSecOps, GCP, PyRIT, Python, 上游代理, 人工智能, 多智能体系统, 安全规则引擎, 无后门, 用户模式Hook绕过, 逆向工具