bashiragutale-gif/vulnerability-scanner

# DepGuard — 自动化依赖漏洞检测系统 这是一个用于自动化软件供应链安全扫描的全栈 MERN 应用程序， 根据论文项目开发计划构建（React + Node.js/Express + MongoDB）。 ## 已实现功能 | 阶段 | 功能 | 位置 | |---|---|---| | 1 | 架构、REST API 设计、数据库 schema | `backend/src/models`, `backend/src/routes` | | 2 | JWT 认证、注册/登录/登出、密码重置、个人资料、三级 RBAC (user/manager/admin) | `backend/src/controllers/authController.js`, `userController.js`, `utils/roles.js` | | 3 | 项目 CRUD、ZIP 上传、GitHub clone/pull、项目历史 | `backend/src/controllers/projectController.js`, `services/githubService.js` | | 4 | 依赖扫描器 (`npm audit` + OSV.dev CVE 交叉引用)、CVSS 分数 | `backend/src/services/dependencyScanner.js`, `services/cveService.js` | | 5 | 源代码扫描器：SQLi、XSS、硬编码密钥、命令注入、弱加密、配置错误 | `backend/src/services/sourceScanner.js` | | 6 | 风险评分引擎、风险分类、优先修复建议 | `backend/src/services/riskEngine.js` | | 7 | 仪表盘统计、PDF 安全报告 | `backend/src/controllers/dashboardController.js`, `services/pdfService.js` | | 8 | 计划的每日/每周/每月扫描、扫描结果对比 | `backend/src/services/scheduler.js`, `scanController.js#compareScans` | | 9 | Jest + Supertest 测试示例 | `backend/tests/auth.test.js` | | 10 | 本 README / 架构文档 | — | ## 技术栈 - **前端：** React 18 + Vite + React Router + Tailwind CSS + Recharts + lucide-react - **后端：** Node.js + Express.js，分层架构为 routes → middleware → controllers → services → models - **数据库：** MongoDB + Mongoose - **认证：** JWT (bearer token)，bcrypt 密码哈希 - **安全工具：** `npm audit`，OSV.dev API，自定义基于 regex 的静态分析器 ## 项目结构 ``` vuln-scanner/ ├── backend/ │ ├── src/ │ │ ├── config/ # DB connection │ │ ├── models/ # Mongoose schemas: User, Project, Scan, Vulnerability, SourceIssue, Report │ │ ├── controllers/ # Route handlers (thin, delegate to services) │ │ ├── middleware/ # auth, error handling, validation, file upload │ │ ├── routes/ # Express routers │ │ ├── services/ # Business logic: scanners, risk engine, GitHub, CVE lookup, PDF, scheduler │ │ └── app.js │ ├── tests/ │ ├── server.js │ └── package.json ├── frontend/ │ ├── src/ │ │ ├── api/ # Axios client + typed endpoint calls │ │ ├── context/ # AuthContext (JWT session state) │ │ ├── components/ # Layout, ScoreGauge, SeverityBadge │ │ ├── pages/ # Login, Register, Dashboard, Projects, ProjectDetail, ScanDetail, AdminUsers │ │ └── routes/ # ProtectedRoute │ └── package.json └── README.md ``` ## 系统角色 标准三级 RBAC，在 `backend/src/utils/roles.js` 中进行服务端强制执行，并按路由应用 （永远不要信任前端进行授权）： | 角色 | 自己的项目 | 其他用户的项目/扫描/报告 | 用户管理 | |---|---|---|---| | `user` (默认) | 完全权限 (创建/扫描/编辑/删除) | 无访问权限 | 否 | | `manager` | 完全权限 | 只读 (查看/下载，不能编辑/删除/触发) | 否 | | `admin` | 完全权限 | 完全权限 | 是 (更改角色、激活/停用、删除) | `manager` 角色专为需要全局安全状况可见性的审计员/主管设立，且 不能触碰其他团队的项目或用户目录。只有 `admin` 可以通过 `PATCH /api/users/:id/role` 提升/降级 角色。 ## 开始使用 ### 前置条件 - Node.js 18+ - 本地运行的 MongoDB 或连接字符串 (Atlas 等) - PATH 中可用的 `git` CLI (用于 GitHub 仓库克隆) ### 后端 ``` cd backend cp .env.example .env # edit MONGO_URI, JWT_SECRET, etc. npm install npm run dev # starts on http://localhost:5000 ``` ### 前端 ``` cd frontend cp .env.example .env # VITE_API_URL=http://localhost:5000/api npm install npm run dev # starts on http://localhost:5173 ``` 打开 http://localhost:5173，注册一个账号，然后创建一个项目 (GitHub URL 或 ZIP 上传) 并点击 **运行扫描**。 ### 运行测试 ``` cd backend npm test ``` ## 各扫描器工作原理 **依赖扫描器** (`services/dependencyScanner.js`) 递归发现项目中的每个 `package.json` (跳过 `node_modules`、`.git`、 构建输出等)，因此典型的全栈布局 —— 一个 React `frontend/` 和一个 Node/Express `backend/`，各自都有自己的清单，且仓库根目录下没有 package.json —— 都会被 完整扫描，而不仅仅是根目录。每个子项目独立扫描：读取 `package.json`/`package-lock.json`，运行 `npm audit --json` 获取权威的 CVE 数据，然后 将每个直接/开发依赖与免费的 OSV.dev API 进行交叉引用，以捕获 npm 注册表 安全公告源遗漏的任何内容。扫描结果会标记 `subProject` (例如 `frontend`、`backend`)，以便在多包仓库中保持结果的可追溯性。 **源代码扫描器** (`services/sourceScanner.js`) 一个无依赖的静态分析器，遍历所有 `.js/.jsx/.ts/.tsx` 文件 (跳过 `node_modules`、`.git`、构建输出) 并标记匹配已知风险模式的代码行： SQL 字符串拼接、`dangerouslySetInnerHTML`/`innerHTML`、硬编码的密钥/API 密钥、 未经过滤的 `exec`/`spawn` 调用、弱哈希 (MD5/SHA1)、通配符 CORS 以及硬编码的 JWT 密钥。 这是一个启发式的初步筛查工具，不能完全替代 SAST —— 请将结果视为需要审查的线索。 **风险引擎** (`services/riskEngine.js`) 通过确定性的严重程度加权扣分，将扫描发现转化为 0–100 的安全评分， 对整体风险进行分类 (低/中/高/严重)，并生成优先升级列表。 **持续监控** (`services/scheduler.js`) `node-cron` 任务每天 (02:00)、每周 (周一 03:00) 和每月 (1 号 04:00) 为每个活跃项目重新运行 `runFullScan()`，因此安全评分趋势和扫描对比能够展示真实的历史记录。 ## 论文撰写的说明与下一步计划 - 密码重置目前在非生产环境响应中直接返回 token，而不是通过电子邮件 发送 —— 在进行任何实际部署之前，需要接入交易邮件服务提供商 (例如 SendGrid/Nodemailer)。 - 源代码扫描器特意设计得简单/基于 regex 以保持无依赖；更强的 版本可以集成 ESLint 安全插件或 Semgrep 规则，以达到第 5 阶段“最佳实践”的标准。 - `npm audit` 在扫描时需要访问互联网连接到 npm 的注册表 —— 如果扫描处于气隙隔离环境下的代码， OSV.dev 交叉引用步骤仍需要出站 HTTPS 连接。 - 如果要投入生产环境，请添加基于用户的限流 (不仅仅是基于 IP) 并为 admin 操作添加审计日志。

标签：DevSecOps, MERN, MITM代理, 上游代理, 安全专业人员, 自定义脚本, 软件供应链安全, 远程方法调用, 错误基检测, 静态代码分析