Irfan-code-cloud/Nexus-Audit-Engine
GitHub: Irfan-code-cloud/Nexus-Audit-Engine
一款基于 GraphRAG 与多智能体架构的自主 DevSecOps 流水线，能够自动检测代码漏洞、诊断 CI/CD 故障根因并直接通过 GitHub Pull Request 提交精准修复补丁。
Stars: 0 | Forks: 0
# 🦇 NEXUS 深度审计引擎
**一个自主安全与 QA 编排流水线**
NEXUS 是一个企业级、多智能体 AI 流水线，旨在摄取、映射、审计并自主修补复杂的代码库。专为 **Agents for Business** 赛道设计，它将传统的 CI/CD 安全瓶颈转化为一个持续的、自我修复的工作流。
*Nexus 指挥中心：一个高科技战术界面，用于初始化向量大脑映射、多智能体审计和自主 PR 流水线。*
*授权门控：如果未安装 GitHub App，将出现此通知。用户可以点击授权按钮，被重定向到 GitHub App 安装页面，在那里他们可以安装并选择允许引擎访问的仓库。* ## 🛑 业务痛点 企业软件开发团队面临着一个关键的操作瓶颈：部署失败和安全漏洞极大地消耗了工程资源。当 CI/CD 流水线崩溃时，DevOps 工程师浪费了无数小时去筛选成千上万行晦涩难懂的 GitHub workflow 日志，仅仅是为了追踪一个缺失的环境变量、一个损坏的 DNS 路由，或者一个跨语言的语法错误。 此外，手动审查 pull request 经常会忽略架构技术债务。迫使高级开发人才暂停能产生收益的功能开发，转而追踪日志并部署手动热修复，会导致发布延迟、停机时间延长以及工程团队精疲力竭。 ## 💡 解决方案 NEXUS 将这一瓶颈转化为一个持续的、自我修复的工作流，将流水线调试和漏洞修补时间从数小时缩短到仅仅几秒钟。作为自主的 DevSecOps 工程师运行，Nexus 直接集成到您的 GitHub 生态系统中，提供两项核心企业级功能： * **即时 CI/CD 流水线诊断：** 当 GitHub Action workflow 失败时，Nexus 会自动拦截并读取原始错误日志。它会立即隔离根本原因并生成精确的“DevOps 顾问报告”，为人类工程师提供确切的、循序渐进的解决方案（例如，具体应该添加哪个 GitHub Secret 或更改哪个配置）。 * **自主自我修复代码：** 引擎使用 FAISS (Facebook AI Similarity Search) 向量大脑映射内部代码依赖关系，以理解任何更改的“爆炸半径”。它会标记关键漏洞并生成逐字节精确的代码替换。最后，它会自主推送一个安全的热修复分支，并打开一个等待人工批准的 Pull Request，无需任何手动编码。 
*自主修补：QA Agent 验证 Architect 的代码生成，提供精确的 search-and-replace diff，随时准备进行一键 pull request。* ## 🏗️ 技术架构与 Agent 角色 ``` graph TD A[GitHub Repository] -->|Connected via App| B(Vector Brain & GraphRAG) B -->|Maps AST Dependencies| C{Tier 1: Auditor Agent} C -->|Extracts Vulnerabilities| D{Tier 2: Architect Agent} D -->|Drafts JSON Patches| E{Tier 3: QA DevOps Agent} E -->|Validates Strict Integrity| F[Autonomous Hotfix PR] E -->|VETO: Hallucination Detected| D ``` 引擎利用高度结构化的多 Agent workflow，通过 FastAPI（后端）和 React（前端）进行编排。 
*实时 Agent 追踪：控制面板以实时可视化展示顺序流水线，Agent 们扫描 AST、起草补丁并验证结构完整性。* 1. **向量大脑：** 当连接到一个仓库时，引擎会将其克隆到内存中并对抽象语法树 (AST) 进行分块。它会映射文件依赖关系，以理解任何潜在代码更改的“爆炸半径”，并将这些上下文存储在由 Google 的 Gemini Embeddings 驱动的本地 FAISS 向量数据库中。 2. **第一梯队：审计 Agent (The Auditor Agent)：** 根据已知的漏洞模式、技术债务标记和模拟的 MCP Server 摄取日志（崩溃日志、Zendesk 工单）扫描向量化代码库。它提取高风险片段及其导入依赖项。 3. **第二梯队：架构师 Agent (The Architect Agent) (由 Groq/Llama 提供支持)：** 分析代码片段并起草 JSON 蓝图。它生成精确的 `search_block` 和 `replace_block` payload 来修复漏洞。 4. **第三梯队：QA Agent (The QA Agent)：** 对抗性的安全网。它严格执行域隔离（防止跨语言幻觉，例如在 JS 文件中建议 Python 代码）并验证逐字节的准确性。如果 Architect 产生幻觉，QA Agent 将启用“一票否决权”(VETO) 并中止补丁。 ### 🏆 展示的 Kaggle 课程概念 * **Agent/多智能体系统：** 严格的 3 层顺序流水线（审计员 -> 架构师 -> QA）。 * **安全特性：** 系统专为漏洞修补而设计，具有“焦土协议”，可在提出补丁之前检测暴露的密钥并对其进行严格脱敏。 * **MCP Server 集成：** 模拟摄取跨平台的生产环境信号（Sentry 日志、App Store 评论）以作为审计目标。 ## 🧠 高级功能 ### DevOps 顾问与根因分析 除了语法错误之外，Nexus 还能诊断系统性的基础设施和配置故障。当系统发生故障时，它会给出包含根本原因和解决方案的通知。 
*当脚本由于端点不可达而崩溃时，引擎会识别出根本原因（例如，来自 GitHub Actions runner 的 DNS 故障），并提供具体的紧急修复建议，例如将硬编码的端点迁移到 GitHub Secrets。* ### 系统账本 
*不可变的系统账本追踪所有历史审计记录、废弃的草稿和已部署的 PR，确保所有 AI 操作完全可追溯。* ### 2. 仓库结构树 ``` Nexus-Audit-Engine/ ├── .env ├── README.md ├── assets/ │ └── (Dashboard UI Screenshots) ├── frontend/ │ └── src/ │ ├── App.jsx │ ├── AuditHistoryModal.jsx │ ├── RollbackModal.jsx │ ├── main.jsx │ ├── App.css │ └── index.css └── backend/ ├── main.py ├── auth_engine.py ├── requirements.txt └── agents/ ├── dependency_mapper.py ├── pr_agent.py └── vector_brain.py ``` ## 🚀 本地设置说明（面向评委） 要在本地运行 Nexus 引擎，您需要同时设置 Python 后端和 React 前端。 ### 前置条件 * Python 3.9+ * Node.js & npm * 一个 GitHub App（用于生成动态安装令牌） ### 🔑 如何为本地测试创建 GitHub App 由于此引擎使用动态的、银行级安装令牌和实时 webhook，您必须在您的账户上创建一个简单的 GitHub App 才能在本地运行它： 1. 启动您的后端服务器（`uvicorn main:app --reload --port 8000`）。 2. 在一个新的终端窗口中，启动 ngrok 以暴露您的本地端口： `ngrok http 8000` 3. 复制您安全的 `ngrok` 转发 URL（例如，`https://1234-abcd.ngrok-free.app`）。 4. 转到您的 GitHub **Settings** > **Developer settings** > **GitHub Apps** > **New GitHub App**。 5. **名称：** Nexus-Audit-Test（或类似名称） & **Homepage URL：** `http://localhost:5173`。 6. **Webhook URL：** 粘贴您的 ngrok URL 并附加 webhook 端点： `https://.ngrok-free.app/api/v1/webhooks/github`
7. **Permissions：** 授予对 **Contents** 和 **Pull requests** 的 `Read & write` 权限。
8. 订阅事件：勾选 **Pull request** 的复选框。
9. 点击 **Create GitHub App**。
10. 在下一个屏幕上，复制您的 **App ID**（用于 `.env` 文件）。
11. 向下滚动并点击 **Generate a private key**。将下载的文件重命名为 `batcomputer-private-key.pem` 并将其放置在 `backend/` 目录中。
12. 最后，在左侧边栏点击 **Install App**，并将其安装到您想要审计的仓库上！
### 1. 克隆仓库
```
git clone https://github.com/Irfan-code-cloud/Nexus-Audit-Engine.git
cd Nexus-Audit-Engine
```
gi
### 2. 后端环境设置
后端需要特定的 API 密钥和 GitHub App 私钥才能运行。
```
# 导航到 backend
cd backend
# 创建并激活 virtual environment
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
# 安装所有项目 dependencies
pip install -r requirements.txt
```
### 创建 .env 文件：
在 `backend/` 目录的根目录下创建一个名为 .env 的文件，并添加您的密钥：
```
GITHUB_APP_ID="your_github_app_id"
GITHUB_TOKEN="your_personal_access_token_fallback"
GEMINI_API_KEY="your_google_gemini_api_key"
GROQ_API_KEY="your_groq_api_key"
GITHUB_WEBHOOK_SECRET="your_webhook_secret"
```
### 添加 GitHub 私钥：
您必须从您的 GitHub App 设置中生成一个私钥 `.pem` 文件。请将此文件完全以 `batcomputer-private-key.pem` 的形式保存在 `backend/` 文件夹中（与 `auth_engine.py` 同级）。
### 3. 前端环境设置
打开一个新的终端窗口以启动战术 Batcomputer 控制面板。
```
# 导航到 frontend
cd frontend
# 安装 dependencies
npm install
# 运行 development server
npm run dev
```
## 🏁 使用指南
1. **启动引擎**：确保后端（`uvicorn main:app --reload`）和前端（`npm run dev`）服务器都在运行。
2. **授权引擎**：在引擎审计代码库之前，您必须授予其访问权限。将您创建的 GitHub App 安装到您想要扫描的特定仓库上（您可以通过点击“Install App”，在您的 GitHub App 设置页面执行此操作）。
3. **连接仓库**：打开前端（`http://localhost:5173`）。将您已授权的 GitHub 仓库 URL 粘贴到连接栏中，然后点击 **Connect** 以同步向量大脑。
4. **执行审计**：一旦仓库成功连接并映射，点击 **Run Deep Code Audit** 以释放多 Agent 流水线。
5. **审查并部署**：系统将处理代码库、识别漏洞，并显示生成的代码补丁。点击 **Merge & Open Pull Request**，将精准的修复直接部署到您的 GitHub 仓库中。
## 🛡️ 安全与架构
* **GitHub App 流程**：系统使用动态 App 安装令牌来安全地与仓库进行身份验证，而无需在代码中存储长期有效的个人访问令牌。
* **向量化上下文**：FAISS 的使用确保了 LLM 已经在上下文中“阅读”了整个代码库，从而能够跨复杂的目录结构进行准确的错误检测。
* **安全循环**：QA Agent 作为最终的“一票否决权”(VETO) 机构，防止 AI 幻觉破坏构建。
## ☁️ 云部署架构
Nexus 审计引擎采用解耦的微服务架构运行，以确保最大的可扩展性和性能。
### 1. 前端：Vercel（指挥中心）
React/Vite 控制面板部署在 **Vercel** 上。
* **为什么选择 Vercel？** Vercel 提供了开箱即用的全球 Edge Network 分发，以近乎零的延迟向用户提供静态 UI 资产。通过将 UI 与后端解耦，React 应用程序保持了极高的响应速度，并且不会消耗 AI Agent 所需的昂贵计算资源。
* **集成：** 前端通过注入的环境变量（`VITE_API_BASE_URL`）与云后端进行安全通信。
### 2. 后端：Google Cloud Run（AI 大脑）
FastAPI AI 编排层作为无服务器容器部署在 **Google Cloud Run** 上。
* **为什么选择 Google Cloud？** 后端需要执行繁重的任务：解析抽象语法树、查询 FAISS 向量数据库，以及管理长时间运行的 LLM 生成流。Google Cloud Run 提供了安全的密钥管理（用于 Groq 和 GitHub 密钥），并在多个 webhook 或审计请求同时到达时无缝自动扩容计算资源。
### 3. 容器化
后端使用包含的 `Dockerfile` 进行了严格的容器化。
* **为什么使用 Docker？** 机器学习依赖项和向量数据库（如 FAISS）对操作系统环境高度敏感。通过利用基于 Linux 的 Docker 容器，我们彻底消除了“在我的机器上是可以运行的”这种问题。
* **工作原理：** `Dockerfile` 拉取经过验证的 Python 3.11 镜像，安装精确的 OS 级依赖项，通过 `requirements_linux.txt` 安装隔离的 Python 包，并通过动态端口映射安全地将应用程序暴露给 Google Cloud Run。
### 开发者
**由 Irfan Khattak 开发 - AI 编排工程师**
*Nexus 指挥中心：一个高科技战术界面，用于初始化向量大脑映射、多智能体审计和自主 PR 流水线。*
*授权门控：如果未安装 GitHub App，将出现此通知。用户可以点击授权按钮，被重定向到 GitHub App 安装页面，在那里他们可以安装并选择允许引擎访问的仓库。* ## 🛑 业务痛点 企业软件开发团队面临着一个关键的操作瓶颈：部署失败和安全漏洞极大地消耗了工程资源。当 CI/CD 流水线崩溃时，DevOps 工程师浪费了无数小时去筛选成千上万行晦涩难懂的 GitHub workflow 日志，仅仅是为了追踪一个缺失的环境变量、一个损坏的 DNS 路由，或者一个跨语言的语法错误。 此外，手动审查 pull request 经常会忽略架构技术债务。迫使高级开发人才暂停能产生收益的功能开发，转而追踪日志并部署手动热修复，会导致发布延迟、停机时间延长以及工程团队精疲力竭。 ## 💡 解决方案 NEXUS 将这一瓶颈转化为一个持续的、自我修复的工作流，将流水线调试和漏洞修补时间从数小时缩短到仅仅几秒钟。作为自主的 DevSecOps 工程师运行，Nexus 直接集成到您的 GitHub 生态系统中，提供两项核心企业级功能： * **即时 CI/CD 流水线诊断：** 当 GitHub Action workflow 失败时，Nexus 会自动拦截并读取原始错误日志。它会立即隔离根本原因并生成精确的“DevOps 顾问报告”，为人类工程师提供确切的、循序渐进的解决方案（例如，具体应该添加哪个 GitHub Secret 或更改哪个配置）。 * **自主自我修复代码：** 引擎使用 FAISS (Facebook AI Similarity Search) 向量大脑映射内部代码依赖关系，以理解任何更改的“爆炸半径”。它会标记关键漏洞并生成逐字节精确的代码替换。最后，它会自主推送一个安全的热修复分支，并打开一个等待人工批准的 Pull Request，无需任何手动编码。 
*自主修补：QA Agent 验证 Architect 的代码生成，提供精确的 search-and-replace diff，随时准备进行一键 pull request。* ## 🏗️ 技术架构与 Agent 角色 ``` graph TD A[GitHub Repository] -->|Connected via App| B(Vector Brain & GraphRAG) B -->|Maps AST Dependencies| C{Tier 1: Auditor Agent} C -->|Extracts Vulnerabilities| D{Tier 2: Architect Agent} D -->|Drafts JSON Patches| E{Tier 3: QA DevOps Agent} E -->|Validates Strict Integrity| F[Autonomous Hotfix PR] E -->|VETO: Hallucination Detected| D ``` 引擎利用高度结构化的多 Agent workflow，通过 FastAPI（后端）和 React（前端）进行编排。 
*实时 Agent 追踪：控制面板以实时可视化展示顺序流水线，Agent 们扫描 AST、起草补丁并验证结构完整性。* 1. **向量大脑：** 当连接到一个仓库时，引擎会将其克隆到内存中并对抽象语法树 (AST) 进行分块。它会映射文件依赖关系，以理解任何潜在代码更改的“爆炸半径”，并将这些上下文存储在由 Google 的 Gemini Embeddings 驱动的本地 FAISS 向量数据库中。 2. **第一梯队：审计 Agent (The Auditor Agent)：** 根据已知的漏洞模式、技术债务标记和模拟的 MCP Server 摄取日志（崩溃日志、Zendesk 工单）扫描向量化代码库。它提取高风险片段及其导入依赖项。 3. **第二梯队：架构师 Agent (The Architect Agent) (由 Groq/Llama 提供支持)：** 分析代码片段并起草 JSON 蓝图。它生成精确的 `search_block` 和 `replace_block` payload 来修复漏洞。 4. **第三梯队：QA Agent (The QA Agent)：** 对抗性的安全网。它严格执行域隔离（防止跨语言幻觉，例如在 JS 文件中建议 Python 代码）并验证逐字节的准确性。如果 Architect 产生幻觉，QA Agent 将启用“一票否决权”(VETO) 并中止补丁。 ### 🏆 展示的 Kaggle 课程概念 * **Agent/多智能体系统：** 严格的 3 层顺序流水线（审计员 -> 架构师 -> QA）。 * **安全特性：** 系统专为漏洞修补而设计，具有“焦土协议”，可在提出补丁之前检测暴露的密钥并对其进行严格脱敏。 * **MCP Server 集成：** 模拟摄取跨平台的生产环境信号（Sentry 日志、App Store 评论）以作为审计目标。 ## 🧠 高级功能 ### DevOps 顾问与根因分析 除了语法错误之外，Nexus 还能诊断系统性的基础设施和配置故障。当系统发生故障时，它会给出包含根本原因和解决方案的通知。 
*当脚本由于端点不可达而崩溃时，引擎会识别出根本原因（例如，来自 GitHub Actions runner 的 DNS 故障），并提供具体的紧急修复建议，例如将硬编码的端点迁移到 GitHub Secrets。* ### 系统账本 
*不可变的系统账本追踪所有历史审计记录、废弃的草稿和已部署的 PR，确保所有 AI 操作完全可追溯。* ### 2. 仓库结构树 ``` Nexus-Audit-Engine/ ├── .env ├── README.md ├── assets/ │ └── (Dashboard UI Screenshots) ├── frontend/ │ └── src/ │ ├── App.jsx │ ├── AuditHistoryModal.jsx │ ├── RollbackModal.jsx │ ├── main.jsx │ ├── App.css │ └── index.css └── backend/ ├── main.py ├── auth_engine.py ├── requirements.txt └── agents/ ├── dependency_mapper.py ├── pr_agent.py └── vector_brain.py ``` ## 🚀 本地设置说明（面向评委） 要在本地运行 Nexus 引擎，您需要同时设置 Python 后端和 React 前端。 ### 前置条件 * Python 3.9+ * Node.js & npm * 一个 GitHub App（用于生成动态安装令牌） ### 🔑 如何为本地测试创建 GitHub App 由于此引擎使用动态的、银行级安装令牌和实时 webhook，您必须在您的账户上创建一个简单的 GitHub App 才能在本地运行它： 1. 启动您的后端服务器（`uvicorn main:app --reload --port 8000`）。 2. 在一个新的终端窗口中，启动 ngrok 以暴露您的本地端口： `ngrok http 8000` 3. 复制您安全的 `ngrok` 转发 URL（例如，`https://1234-abcd.ngrok-free.app`）。 4. 转到您的 GitHub **Settings** > **Developer settings** > **GitHub Apps** > **New GitHub App**。 5. **名称：** Nexus-Audit-Test（或类似名称） & **Homepage URL：** `http://localhost:5173`。 6. **Webhook URL：** 粘贴您的 ngrok URL 并附加 webhook 端点： `https://
标签：AI智能体, DevSecOps, GraphRAG, 上游代理, 自动化代码修复, 自定义脚本, 请求拦截, 逆向工具