varshitha17041943/Trust_Guard

# TrustGuardAI 🛡️     一个企业级、多 Agent 的网络安全威胁情报平台。 专为 **Google AI Agents Capstone** 打造。 ## 📖 项目概述 ### 问题陈述 现代网络威胁（例如零日钓鱼活动和域名抢注攻击）能够绕过传统的启发式防火墙。此外，现有的威胁情报工具会直接输出原始且高度技术化的 JSON payload（例如 `ERR_SSL_PROTOCOL_ERROR`），非技术用户根本无法解读，这使他们容易受到社会工程学攻击。 ### 解决方案 TrustGuardAI 弥合了深度技术情报与人类可读性之间的鸿沟。通过利用异步的、基于 DAG 的 **多 Agent 系统 (Antigravity Engine)**，该平台通过 **Model Context Protocol (MCP)** 查询全球威胁数据库（VirusTotal、Google Safe Browsing、crt.sh）。 随后，一个专门的 **可解释 AI (XAI)** Agent 会拦截这些技术标志，并将其转化为具有教育意义、可执行的英文描述，最终在精美的 Glassmorphism 仪表板上呈现结果。 ## ✨ 核心功能 - **真正的多 Agent 编排**：9 个独立的 Google ADK Agent 在高度优化的有向无环图 (DAG) pipeline 中运行。 - **Model Context Protocol (MCP)**：严格的整洁架构。核心后端**绝不**发起直接的外部 HTTP 请求。所有情报收集均通过受有状态 Circuit Breaker 保护的独立 MCP 服务器进行安全传输。 - **可解释 AI (XAI)**：将原始 JSON 转化为教育提示、UI 折叠面板和个性化的 AI 建议。 - **企业级报告**：动态生成并下载专业的 PDF、Markdown 和 JSON 安全报告。 - **高级分析**：基于 TTL 缓存的 PostgreSQL 聚合数据，提供实时的 Recharts 可视化图表。 ## 🛠️ 技术栈 - **前端**：React 18, TypeScript, TailwindCSS, Framer Motion, Recharts, Vitest - **后端**：FastAPI, SQLAlchemy (asyncpg), Pydantic, Pytest - **多 Agent 编排**：自定义 `Antigravity` DAG 引擎 (Python `asyncio`) - **协议**：运行在端口 `8001` 的自定义 Model Context Protocol (MCP) 服务器 - **数据库**：PostgreSQL 15（带有 `pgvector`，可用于未来的 embedding 支持） - **容器化**：Docker, Docker Compose, GitHub Actions CI/CD ## 🏛️ 架构与开发者指南 ### 1. 整体流程 ``` graph LR A[React Frontend] -->|SSE Stream| B(FastAPI Backend) B -->|Task Dispatch| C{Antigravity Orchestrator} C -->|Phase 1| D[Input Validation Agent] C -->|Phase 2| E[Security Analysis Agent] E <-->|Signed HTTP Request| F((MCP Server :8001)) F <-->|Lookup| G[VirusTotal API] F <-->|Lookup| H[Google Safe Browsing] C -->|Phase 3| I[Risk Assessment Agent] C -->|Phase 4| J[Explainable AI Agent] I --> K[(PostgreSQL)] ``` ### 2. Google ADK 多 Agent 引擎 我们自定义的 `Antigravity` 引擎编排了 9 个高度隔离的 AI agent。每个 agent 在通过 pipeline 时，都会修改一个 Pydantic `SharedContext` 状态对象。 ``` graph TD subgraph Ingestion Phase A[InputValidationAgent] B[QRProcessingAgent] end subgraph Intelligence Phase C[SecurityAnalysisAgent] D[BrandVerificationAgent] end subgraph Assessment Phase E[RiskAssessmentAgent] end subgraph Synthesis Phase F[ExplanationAgent] G[RecommendationAgent] H[OfficialWebsiteAgent] I[ReportGenerationAgent] end A & B --> C & D C & D --> E E --> F & G & H & I ``` ### 3. Model Context Protocol (MCP) 服务器 后端完全免受外部 API 故障的影响。如果 VirusTotal 遇到 `429 Too Many Requests`，MCP 的 Circuit Breaker 将跳转为 `OPEN` 状态，并将规范化的兜底数据注入到多 Agent pipeline 中，从而防止死锁。 ``` graph TD A[FastAPI Backend] -->|MCP Request| B{Circuit Breaker} B -->|CLOSED| C[Tool Registry] C --> D[VirusTotal Tool] C --> E[GSB Tool] C --> F[SSL Tool] B -->|OPEN| G[Fallback Generator] G -->|Normalized Safe Data| A D & E & F -->|Normalized Threat Data| A ``` ### 4. 数据库 ER 图 ``` erDiagram USERS ||--o{ SCANS : executes SCANS ||--o{ THREAT_RESULTS : generates SCANS ||--o{ RECOMMENDATIONS : receives SCANS ||--o| OFFICIAL_WEBSITES : verifies ``` ## 📂 项目结构 ``` TrustGuardAI/ ├── backend/ # FastAPI Main Application │ ├── app/ │ │ ├── agents/ # The 9 Google ADK Agents │ │ ├── controllers/ # API Routers (Auth, Scan, Analytics) │ │ ├── models/ # SQLAlchemy ORM Models │ │ ├── services/ # Business Logic (JWT, PDFs) │ │ ├── workflows/ # Antigravity DAG Orchestrator │ │ └── main.py # FastAPI Entrypoint │ ├── tests/ # Pytest Suite │ └── Dockerfile ├── frontend/ # React UI │ ├── src/ │ │ ├── components/ # Reusable Glassmorphism UI │ │ ├── pages/ # Dashboard, Results, Scanners │ │ └── tests/ # Vitest Suite │ └── Dockerfile ├── mcp/ # Standalone MCP Server │ ├── tools/ # Extensible Tool Registry │ ├── server.py # MCP Entrypoint (:8001) │ └── Dockerfile ├── docker-compose.yml # Orchestrates 4 Containers └── README.md # You are here ``` ## ⚡ 设置与安装 ### 环境变量 在 `mcp/` 目录下创建一个 `.env` 文件。（如果留空，Circuit Breaker 将优雅地处理兜底数据）。 ``` VIRUSTOTAL_API_KEY=your_vt_key GOOGLE_SAFE_BROWSING_API_KEY=your_gsb_key ``` ### 通过 Docker 运行（推荐） 确保您已安装 Docker Engine 和 Docker Compose。在根目录下执行以下命令： ``` docker-compose up --build -d ``` 架构将在 4 个相互隔离的容器中启动： 1. `db`：运行在 `5432` 端口的 PostgreSQL 数据库。 2. `mcp`：运行在 `8001` 端口的 MCP 服务器。 3. `backend`：运行在 `8000` 端口的 FastAPI 引擎。 4. `frontend`：运行在 `3000` 端口的 Nginx，用于提供 React 服务。 在浏览器中访问 **http://localhost:3000**。 ### 云端部署 - **前端**：将 `frontend/` 目录部署到 **Vercel**，构建命令为 `npm run build`。 - **后端和 MCP**：将 `backend/Dockerfile` 和 `mcp/Dockerfile` 部署到 **Google Cloud Run** 或 **Render**，确保 `MCP_SERVER_URL` 环境变量指向内部的 MCP IP 地址。 ## 📚 API 文档 一旦后端运行起来，您可以在以下地址访问带有完整文档的 OpenAPI 接口： 👉 `http://localhost:8000/docs` ### 请求示例 (`POST /api/scan/url`) ``` { "target": "https://paypal-secure-login.com" } ``` ### Server-Sent Events (SSE) 流示例 ``` data: {"step": "SecurityAnalysisAgent", "status": "running"} data: {"step": "SecurityAnalysisAgent", "status": "complete", "result": {"threat_intel_flags": ["VT_FLAG", "GSB_FLAG"]}} ``` ## 📸 截图 *(将这些占位符替换为您仓库中的实际截图)* | Dashboard | Real-time SSE Scanning | |-----------|------------------------| | `` | `` | | Explainable AI Results | PDF Report Generation | |------------------------|-----------------------| | `` | `` | ## 🔮 未来规划 - **LLM Embedding**：集成 `pgvector` 以对历史威胁报告执行语义搜索。 - **浏览器扩展**：将 React 应用移植为 Chrome 扩展程序，以实现实时的 URL 拦截。 - **动态 Kubernetes**：将各个独立的 ADK Agent 作为单独的无服务器函数进行编排。 ## 🙌 致谢 由 varsh 为 **Google AI Agents Capstone** 构建。 感谢 FastAPI、React 和 Recharts 背后的开源社区。 ## 📄 许可证 本项目基于 MIT 许可证授权 - 有关详细信息，请参阅 [LICENSE](LICENSE) 文件。

标签：AV绕过, FastAPI, React, Syscalls, 多智能体, 威胁情报, 开发者工具, 测试用例, 版权保护, 网络安全, 请求拦截, 逆向工具, 钓鱼检测, 隐私保护