LaplaceMkhabela/khusela-ai

# Khusela AI - 智能依赖漏洞扫描器 [](https://nodejs.org) [](LICENSE) [](http://makeapullrequest.com) Khusela AI 是一款复杂的企业级依赖漏洞扫描器，它能分析 Node.js 项目依赖，对照 NVD (National Vulnerability Database) 进行检查，并利用由 Groq 的 Llama 3.1 驱动的 AI 生成包含可操作修复建议的安全报告。 ## 📸 截图 ### 🏠 首页 *展示 Khusela AI 功能和架构的高影响力入口*  *首页包含带有依赖可视化的 hero 区域、展示核心功能的 bento grid 以及 AI 洞察预览。* ### 🔍 扫描界面 *简化的拖放式清单上传器，支持 GitHub 仓库*  *上传 package.json、package-lock.json 或 yarn.lock 文件，或直接连接 GitHub 仓库进行即时扫描。* ### 📊 仪表盘 *包含交互式图表和漏洞清单的数据丰富的概览*  *综合仪表盘包含严重程度分布图表、漏洞最多的包、AI 修复洞察以及详细的漏洞表格。* ### 📜 历史记录页面 *用于管理过往扫描的专业审计日志*  *完整的扫描历史记录，包含搜索、过滤、分页功能，以及显示严重威胁和扫描统计数据的分析卡片。* ## ✨ 功能 | 功能 | 描述 | |---------|-------------| | **🤖 AI 驱动的分析** | Groq Llama 3.1 生成具有可操作建议的人类可读的安全摘要 | | **📦 多文件支持** | 扫描 `package.json`、`package-lock.json` 和 `yarn.lock` 文件 | | **🔗 GitHub 集成** | 通过 HTTPS URL 直接连接到公开的 GitHub 仓库 | | **📊 交互式仪表盘** | 展示漏洞严重程度分布的可视化图表 (Critical/High/Medium/Low) | | **💡 智能修复建议** | AI 推荐的版本升级及可复制的 npm 命令 | | **📜 扫描历史** | 所有扫描的完整审计跟踪，具备搜索和过滤功能 | | **📄 导出报告** | 将结果下载为 JSON、Markdown 或 CSV 格式 | | **🎨 现代 UI** | 具有毛玻璃效果和响应式设计的精美暗色主题 | | **♿ 模态对话框** | 用于修复建议和通知的简洁、非侵入式对话框 | | **⚡ 实时进度** | 扫描执行期间显示动画进度指示器 | | **💾 本地缓存** | NVD API 响应缓存，以最小化速率限制问题 | ## 🏗️ 架构 ``` ┌─────────────────────────────────────────────────────────────────┐ │ Client Browser │ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │ │Landing │ │ Scan │ │Dashboard│ │ History │ │ │ │ Page │ │ Page │ │ Page │ │ Page │ │ │ └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘ │ │ │ │ │ │ │ │ └───────────┴───────────┴───────────┘ │ │ │ │ │ REST API Calls │ └─────────────────────────┼───────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ Express.js Server │ │ ┌─────────────────────────────────────────────────────────┐ │ │ │ API Endpoints │ │ │ │ /api/analyze │ /api/analyze-repo │ /api/export │ │ │ │ /api/history │ /api/scan/:id │ /api/fix │ │ │ └─────────────────────────────────────────────────────────┘ │ │ │ │ │ ┌────────────────┼────────────────┐ │ │ ▼ ▼ ▼ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │ Scanner │ │ Lock File │ │ AI Agent │ │ │ │ Module │ │ Scanner │ │ (Groq LLM) │ │ │ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │ │ │ │ │ │ │ └────────────────┼────────────────┘ │ │ ▼ │ │ ┌─────────────┐ │ │ │ NVD API │ │ │ │ (CVE Data) │ │ │ └─────────────┘ │ └─────────────────────────────────────────────────────────────────┘ ``` ## 🛠️ 技术栈 | 层级 | 技术 | |-------|------------| | **前端** | HTML5, CSS3, TailwindCSS, JavaScript, Chart.js, Marked.js | | **后端** | Node.js, Express.js | | **AI/ML** | Groq SDK (Llama 3.1 8B) | | **安全 API** | NVD REST API v2.0 | | **文件处理** | Multer | | **HTTP 客户端** | Fetch API | | **缓存** | 本地 JSON 文件系统 | ## 📁 项目结构 ``` vulnscan-ai/ ├── server.js # Main Express server with API endpoints ├── package.json # Project dependencies and scripts ├── .env # Environment variables ├── scanner/ │ ├── scanner.js # package.json scanner │ └── scanLockFile.js # Lock file scanner (npm/yarn) ├── agents/ │ └── summarizeReport.js # Groq AI integration for summaries ├── public/ │ ├── landing.html # Marketing/landing page │ ├── scan.html # File upload & repo scan interface │ ├── dashboard.html # Vulnerability dashboard with charts │ └── history.html # Scan history with search/filter ├── cache/ │ └── nvd-cache.json # Cached NVD API responses ├── logs/ # Application logs └── screenshots/ # Documentation screenshots ``` ## 🚀 快速开始 ### 前置条件 - Node.js 16+ - npm 或 yarn - Groq API Key (提供免费层级) ### 安装 ``` # 克隆仓库 git clone https://github.com/LaplaceMkhabela/khusela-ai.git cd khusela-ai # 安装依赖 npm install # 创建所需目录 mkdir -p cache logs # 复制环境变量 cp .env.example .env # 将你的 Groq API key 添加到 .env # GROQ_API_KEY=your_key_here # 启动服务器 npm start ``` ### 环境变量 在根目录下创建一个 `.env` 文件： ``` # Groq API 配置 GROQ_API_KEY=your_groq_api_key_here # 服务器配置 PORT=5000 NODE_ENV=development # NVD API 配置（可选 - 提高 rate limits） NVD_API_KEY=your_nvd_api_key_here # Cache 配置 CACHE_ENABLED=true CACHE_FILE=./cache/nvd-cache.json # 日志 LOG_LEVEL=info LOG_DIR=./logs ``` ### 运行应用 ``` # 开发模式（启用 auto-reload） npm run dev # 生产模式 npm start # 清理 cache npm run clean # 完整设置 npm run setup ``` 打开浏览器并访问： - **首页：** `http://localhost:5000/` - **扫描页面：** `http://localhost:5000/scan` - **仪表盘：** `http://localhost:5000/dashboard` - **历史记录：** `http://localhost:5000/history` ## 📖 使用指南 ### 1. 扫描本地文件 1. 导航至 **Scan** 页面 2. 拖放您的 `package.json`、`package-lock.json` 或 `yarn.lock` 文件 3. 或点击“Browse Files”从您的计算机中选择 4. 观察 VulnScan AI 分析您的依赖时的进度动画 5. 查看结果，包括： - 扫描的包数量 - 按严重程度分类发现的漏洞 - AI 生成的安全摘要 - 带有 CVE 的易受攻击的包列表 ### 2. 扫描 GitHub 仓库 1. 点击扫描页面上的 **"Connect Repo"** 按钮 2. 输入公开的 GitHub 仓库 URL (例如，`https://github.com/facebook/react`) 3. 可选择指定分支名称 (默认为 `main`) 4. 点击 **"Scan Repository"** 5. VulnScan AI 将通过 GitHub API 直接获取 `package.json` 并进行分析 ### 3. 查看仪表盘 - **严重程度分布：** 展示漏洞分类的交互式甜甜圈图 - **AI 修复洞察：** LLM 生成的安全建议 - **易受攻击的顶级包：** 存在最多问题的包列表 - **漏洞清单：** 包含 CVE ID、严重程度和修复操作的详细表格 ### 4. 导出报告 点击仪表盘上的 **JSON** 或 **CSV** 按钮以导出漏洞数据，以便与其他工具集成。 ### 5. 查看扫描历史 **History** 页面维护了完整的审计日志，包含： - 按文件名或扫描 ID 搜索 - 按严重程度过滤 - 针对大量历史记录的分页 - 带有汇总统计数据的分析卡片 ## 🔌 API 端点 | 端点 | 方法 | 描述 | |----------|--------|-------------| | `/api/analyze` | POST | 上传并扫描清单文件 | | `/api/analyze-repo` | POST | 扫描公开的 GitHub 仓库 | | `/api/export-report` | POST | 导出 JSON/CSV 格式的报告 | | `/api/scan-history` | GET | 检索所有扫描历史 | | `/api/scan/:id` | GET | 通过 ID 获取特定的扫描 | | `/api/fix-suggestions` | POST | 获取 AI 驱动的升级建议 | ## 🎯 API 调用示例 ### 上传文件 ``` curl -X POST http://localhost:5000/api/analyze \ -F "jsonFile=@package.json" ``` ### 扫描仓库 ``` curl -X POST http://localhost:5000/api/analyze-repo \ -H "Content-Type: application/json" \ -d '{"repoUrl": "https://github.com/expressjs/express", "branch": "master"}' ``` ### 获取扫描历史 ``` curl http://localhost:5000/api/scan-history ``` ## ⚙️ 配置选项 ### 速率限制 NVD API 具有速率限制。VulnScan AI 包含： - 请求之间 **6.5 秒延迟** - 结果的 **本地缓存**，以最小化 API 调用 - 用于更高速率限制的 **可选 API key** (每 30 秒 50 次请求) ### 缓存管理 缓存文件存储在 `./cache/nvd-cache.json` 中。要清除缓存： ``` npm run clean # 或 rm -rf cache/*.json ``` ### 自定义端口 在您的 `.env` 文件中更改端口： ``` PORT=3000 ``` ## 📝 许可证 本项目基于 MIT 许可证授权 - 有关详细信息，请参阅 [LICENSE](LICENSE) 文件。 ## 🙏 致谢 - [Groq](https://groq.com/) 提供高性能的 LLM 推理 - [NVD](https://nvd.nist.gov/) 提供全面的 CVE 数据库 - [TailwindCSS](https://tailwindcss.com/) 提供精美的实用优先的 CSS 框架 - [Chart.js](https://www.chartjs.org/) 提供交互式数据可视化 **由 Khusela AI 团队使用 🔒 构建**

标签：AI分析, GNU通用公共许可证, MITM代理, Node.js, NVD, 后端开发, 数据可视化