surendra-2407/risk-checker-app

# 🛡️ Risk Checker — Pre-Commit 安全扫描器 一款全栈安全工具，可在你的代码进入生产环境之前，扫描其中的**机密信息、漏洞和风险模式**。 支持三种使用方式：**Web UI**、**Git Hook** 和 **GitHub Webhooks**。 🌐 **在线应用:** https://risk-checker-app.vercel.app ⚙️ **后端 API:** https://risk-checker-app-1.onrender.com ## 🚀 快速开始（本地开发） ``` # 克隆 repo git clone https://github.com/surendra-2407/risk-checker-app.git cd risk-checker-app # 设置 Backend cd risk-checker-backend npm install cp .env.example .env # fill in your API keys npm run dev # → http://localhost:5000 # 设置 Frontend (新终端) cd risk-checker-frontend npm install npm run dev # → http://localhost:5173 # Seed admin account (仅首次) cd risk-checker-backend node scripts/seedAdmin.js ``` ## 🔁 使用 Risk Checker 的 3 种方式 ### 1. 🖥️ Web UI — 手动扫描 **最适合：** 希望在提交前检查代码的开发者。 **工作原理：** 1. 打开 https://risk-checker-app.vercel.app 并登录（Google、GitHub 或电子邮件） 2. 进入 **Scan Code** 页面 3. 将你的代码粘贴到编辑器中 4. 点击 **Scan** — 结果会立即显示 5. 查看你的**风险评分 (0–100)**、风险等级以及完整的问题列表 6. 如果需要，可以下载 **PDF 报告** **检测内容：** | 类别 | 示例 | |---|---| | 🔴 机密信息 | 硬编码在代码中的 API 密钥、密码、token | | 🔴 Injection | `eval()`, `Function()`, `innerHTML` | | 🔴 SQL Injection | 使用用户输入构建的动态查询 | | 🔴 Command Injection | 带有未验证输入的 `exec()` | | 🟡 Cryptography | 像 MD5、`Math.random()` 这样的弱哈希 | | 🟢 调试代码 | `console.log`, `debugger` 语句 | | 🟢 代码质量 | TODO / FIXME 注释 | **风险评分说明：** | 分数 | 等级 | 是否允许提交？ | |---|---|---| | 0 – 20 | 🟢 低 | ✅ 是 | | 21 – 50 | 🟡 中 | ✅ 是（带有警告） | | 51 – 80 | 🔴 高 | ⛔ 阻止 | | 81 – 100 | 🔴 严重 | ⛔ 阻止 | ### 2. 🔗 Git Hook — 每次提交时自动扫描 **最适合：** 希望在风险提交被推送**之前**自动阻止它的开发者。 **工作原理：** 1. 在你的项目中安装一次该 hook（耗时 30 秒） 2. 每次运行 `git commit` 时，该 hook 都会**在后台自动运行** 3. 你的暂存文件将被发送到 Risk Checker 后端进行扫描 4. 如果风险评分 ≤ 50 → ✅ 提交通过 5. 如果风险评分 > 50 → ⛔ 提交被**阻止**，并生成完整的报告 #### 📥 逐步安装 Hook **步骤 1 — 导航到你的项目根目录（即包含 `.git/` 文件夹的位置）：** ``` cd /path/to/your-project ``` **步骤 2 — 复制 hook 文件：** **Mac / Linux / WSL:** ``` bash git-hook/install-hook.sh ``` **Windows (PowerShell):** ``` copy git-hook\pre-commit .git\hooks\pre-commit ``` **步骤 3 — 将 hook 指向在线后端（无需本地服务器）：** 添加到你的 shell 配置文件（`~/.bashrc` 或 `~/.zshrc`）中： ``` export RISK_CHECKER_API=https://risk-checker-app-1.onrender.com ``` 或者仅应用于当前会话： ``` export RISK_CHECKER_API=https://risk-checker-app-1.onrender.com ``` #### 🧪 测试 Hook **测试 1 — 安全代码（提交应被批准）：** ``` echo "const greeting = 'hello world';" > test-safe.js git add test-safe.js git commit -m "test: safe code" # 预期: ✅ Commit approved — 未检测到安全问题！ ``` **测试 2 — 风险代码（提交应被阻止）：** ``` echo "const API_KEY = 'sk-live-abc123secretkey';" > test-risky.js git add test-risky.js git commit -m "test: risky code" # 预期: ⛔ COMMIT BLOCKED — Risk score 超过阈值 (50) ``` **测试 3 — 验证 hook 是否已安装：** ``` ls .git/hooks/pre-commit # 应打印: .git/hooks/pre-commit ``` #### 📟 终端输出 当提交被**阻止**时： ``` 🛡️ Pre-Commit Risk Checker — scanning staged changes... Developer : Surendra Branch : main Repository: my-project ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Risk Score : 78 / 100 Risk Level : Critical Total Issues: 5 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ⛔ COMMIT BLOCKED — Risk score (78) exceeds threshold (50) → View full report at: https://risk-checker-app.vercel.app/results → Fix the issues above and try again, or run: git commit --no-verify (force commit, NOT recommended) ``` 当提交被**批准**时： ``` ✅ Commit approved — no security issues detected! ``` **绕过 hook（仅限紧急情况）：** ``` git commit --no-verify ``` ### 3. 🪝 GitHub Webhook — Push 时自动扫描 **最适合：** 希望对每一次推送到 GitHub 的代码进行自动扫描的团队。 **工作原理：** 1. 每当有代码被推送时，GitHub 都会向后端发送通知 2. 后端自动扫描该提交 3. 结果存储在数据库中 4. 管理员可以从 **Admin Dashboard** 查看所有扫描记录 5. 提交作者将收到一封包含扫描结果的电子邮件 **设置方法：** 1. 进入你的 GitHub 仓库 → **Settings → Webhooks → Add webhook** 2. 将 **Payload URL** 设置为： https://risk-checker-app-1.onrender.com/api/webhooks/github 3. 将 **Content type** 设置为 `application/json` 4. 选择事件：**Just the push event** 5. 点击 **Add webhook** ## 👤 用户角色 | 角色 | 权限 | |---|---| | **User** | 登录、扫描代码、查看自己的历史记录、下载 PDF 报告 | | **Admin** | 包含上述所有权限 + 查看所有用户的扫描记录、完整的分析仪表板 | **登录选项：** - 📧 电子邮件和密码（带电子邮件验证） - 使用 Google 继续 - 使用 GitHub 继续 ## 🔑 环境变量 复制 `risk-checker-backend/.env.example` → `risk-checker-backend/.env` 并填写： ``` # ── Server ─────────────────────────────────────────────────── PORT=5000 NODE_ENV=development FRONTEND_URL=http://localhost:5173 # ── Database ───────────────────────────────────────────────── MONGODB_URI=mongodb+srv://:@cluster.mongodb.net/risk-checker # ── Security ───────────────────────────────────────────────── JWT_SECRET=any_long_random_64_char_string # ── AI (Google Gemini) ─────────────────────────────────────── GEMINI_API_KEY=AIzaSy... # From aistudio.google.com # ── GitHub OAuth + API ─────────────────────────────────────── GITHUB_TOKEN=ghp_... # From github.com/settings/tokens GITHUB_CLIENT_ID=... # From GitHub OAuth App GITHUB_CLIENT_SECRET=... GITHUB_CALLBACK_URL=http://localhost:5000/api/auth/github/callback GITHUB_WEBHOOK_SECRET=... # Optional — for webhook HMAC signature verification # ── Google OAuth ───────────────────────────────────────────── GOOGLE_CLIENT_ID=... # From console.cloud.google.com GOOGLE_CLIENT_SECRET=... GOOGLE_CALLBACK_URL=http://localhost:5000/api/auth/google/callback # ── Secret Detection ───────────────────────────────────────── GITGUARDIAN_API_KEY=... # From dashboard.gitguardian.com # ── ML Classification ──────────────────────────────────────── HUGGINGFACE_API_KEY=hf_... # From huggingface.co/settings/tokens # ── Email (Brevo) ──────────────────────────────────────────── BREVO_API_KEY=xkeysib-... # From app.brevo.com BREVO_FROM_EMAIL=you@gmail.com BREVO_FROM_NAME=Risk Checker # ── Admin Seed ─────────────────────────────────────────────── ADMIN_EMAIL=admin@example.com ADMIN_PASSWORD=YourAdminPassword ``` 前端 `.env` (`risk-checker-frontend/.env`)： ``` VITE_API_URL=http://localhost:5000 ``` **对于生产环境：** 使用 `https://risk-checker-app-1.onrender.com` 作为回调 URL，并设置 `FRONTEND_URL=https://risk-checker-app.vercel.app`。 ## 📁 项目结构 ``` risk-checker-app/ ├── risk-checker-backend/ # Node.js + Express API (port 5000) │ ├── engine/ # Scanner & risk scorer logic │ ├── models/ # MongoDB schemas (User, Commit, Issue, Admin) │ ├── routes/ # API endpoints │ ├── scripts/ # seedAdmin.js │ ├── services/ # AI, GitHub, Email integrations │ └── server.js # App entry point │ ├── risk-checker-frontend/ # React 19 + Vite 8 + TailwindCSS │ └── src/ │ ├── pages/ # All page components │ ├── components/ # Navbar, IssueCard, RiskGauge etc. │ └── lib/ # API client (api.js) │ ├── git-hook/ # Pre-commit hook files │ ├── pre-commit # The hook script (sh) │ └── install-hook.sh # Installer (Mac/Linux/WSL) │ ├── render.yaml # Render.com deployment config └── REQUIREMENTS.md # Full package list & setup guide ``` ## 🆚 Risk Checker 与 `.gitignore` 的区别 — 有何不同？ | 功能 | `.gitignore` | Risk Checker | |---|---|---| | 对 Git 隐藏 `.env` 文件 | ✅ 是 | ❌ 不是它的职责 | | 检测 `.js` 文件**内部硬编码**的 API 密钥 | ❌ 否 | ✅ 是 | | 检测代码中的 SQL Injection 模式 | ❌ 否 | ✅ 是 | | 检测 `eval()`, `innerHTML` 滥用 | ❌ 否 | ✅ 是 | | 自动阻止风险提交 | ❌ 否 | ✅ 是（通过 hook） | | 在风险推送时向开发者发送电子邮件 | ❌ 否 | ✅ 是（通过 webhook） | **总结：** `.gitignore` 用于对 Git 隐藏整个文件。Risk Checker 则会扫描你已提交文件**内部的内容**以查找安全问题。将两者结合使用可实现最大的安全性。

标签：DevSecOps, IaC 扫描, MITM代理, StruQ, 上游代理, 人工智能, 代码安全审计, 用户模式Hook绕过, 自定义脚本, 静态应用安全测试