扫描任何 QR 码或 URL，立即知晓其是否安全。
QR Guard 使用多个安全引擎和 AI 分析链接是否存在钓鱼、恶意软件和诈骗行为。
它会追踪每一次重定向，以可视化方式计算风险评分，并提供清晰易读的安全报告。
安全的 QR 码扫描器与威胁检测平台
## 功能
### 基于 AI 的 QR 码安全扫描器
上传 QR 码图片、拖放文件或直接粘贴 URL。QR Guard 会即时解码并分析 QR 码，以便在用户与其交互之前识别钓鱼企图、恶意链接、诈骗和其他在线威胁。
### 高级 URL 和 QR 码威胁检测
每次扫描都会使用多个威胁情报源和基于 AI 的分析进行全面安全检查，以检测钓鱼网站、恶意软件分发、欺诈性域名和可疑重定向。
### 多引擎安全分析
QR Guard 结合了多个安全引擎以实现准确的威胁检测：
- **VirusTotal** – 全球反病毒和恶意软件情报网络
- **Google Safe Browsing** – 实时检测钓鱼和恶意网站
- **URLhaus** – 协作式的恶意软件和滥用追踪数据库
- **Groq Llama 3 AI** – 基于 AI 的 URL 安全分析，可评估域名模式、重定向行为、钓鱼指标和社会工程学风险
### 重定向链监控
追踪 URL 链中的每一次重定向，揭示隐藏的目的地，识别域名切换技术，检测可疑的重定向循环，并揭露缩短或伪装链接背后的真实目的地。
### QR 钓鱼与诈骗检测
识别常见的钓鱼指标，包括虚假登录页面、银行诈骗、加密货币欺诈、账户验证陷阱、凭据窃取企图，以及其他通常通过 QR 码传播的恶意活动。
### 智能风险评分
通过可视化的风险评分和清晰的分类，获得易于理解的安全评估：
- 安全
- 可疑
- 危险
风险计算会考虑 HTTPS 安全性、域名信誉、重定向行为、关键字分析、基于 IP 的托管以及多个威胁情报信号。
### 扫描历史与安全报告
访问包含搜索、过滤和威胁状态追踪的详细扫描历史记录。随时查看以前的 QR 码和 URL 安全分析。
### 安全的用户身份验证
由 Clerk 身份验证提供支持的用户账户受到保护，可安全访问扫描历史记录、账户设置和订阅功能。
### 现代化的用户体验
享受响应迅速、适合移动设备的仪表板，支持深色模式和浅色模式，采用现代 Web 技术构建，提供快速可靠的性能。
## 技术栈
| 层级 | 技术 |
|---|---|
| Frontend | React 19, TypeScript, Vite 6, Tailwind CSS v4 |
| Backend | Vercel Serverless Functions (Node.js, TypeScript) |
| Auth | Clerk |
| AI | Groq (Llama-3.3-70b) |
| Threat Intel | VirusTotal v2, Google Safe Browsing v4, URLhaus |
| Dev Server | Express + Vite 中间件（通过 `tsx`） |
| Hosting | Vercel (static SPA + serverless API) |
## 快速开始
### 前置条件
- Node.js 18+
- npm
### 安装
```
git clone https://github.com/ogtamimi/qr-guard.git
cd qr-guard
npm install
```
### 环境变量
复制示例文件并填入你的密钥：
```
cp .env.example .env
```
| 变量 | 说明 |
|---|---|
| `GROQ_API_KEY` | 用于 Llama-3 AI 分析的 Groq API 密钥 |
| `VITE_CLERK_PUBLISHABLE_KEY` | Clerk publishable key（客户端） |
| `CLERK_SECRET_KEY` | Clerk secret key（服务端） |
| `VIRUSTOTAL_API_KEY` | VirusTotal v2 API 密钥 |
| `GOOGLE_SAFE_BROWSING_API_KEY` | Google Safe Browsing v4 API 密钥 |
所有密钥都是可选的——缺失的密钥会优雅降级。扫描仍然会使用启发式算法和已配置的引擎正常运行。
### 本地运行
```
npm run dev
```
在 `http://localhost:3000` 启动 Express + Vite 开发服务器。
### 生产构建
```
npm run build
npm start
```
使用 Vite 构建 Frontend，并将 `server.ts` 打包到 `dist/` 中，然后使用 Express 提供 SPA 服务。
### 部署到 Vercel
将代码推送到 GitHub 并在 [Vercel dashboard](https://vercel.com) 中导入该仓库。`vercel.json` 配置会处理 SPA 路由重写；`api/` 中的 API 函数会自动部署为 serverless functions。
## 工作原理
1. **输入** - 用户上传 QR 图片（在客户端使用 jsQR 解码）或粘贴 URL
2. **扫描请求** - 发送至 `POST /api/scan`
3. **重定向追踪** - 追踪完整的 HTTP 重定向链，最多 8 跳，支持手动重定向模式
4. **并行威胁查询** - 同时查询 VirusTotal、Google Safe Browsing 和 URLhaus
5. **DNS 解析** - 解析 A、NS 和 MX 记录以验证域名基础设施
6. **启发式评分** - 根据收集到的所有信号计算基础风险评分
7. **AI 增强** - 如果设置了 `GROQ_API_KEY`，扫描元数据将发送给 Llama-3.3-70b 进行语义分析，并生成自然语言风险报告
8. **响应** - 在仪表板中展示组合结果
## API 参考
### `POST /api/scan`
扫描 URL 以检测安全威胁。
**请求体：**
```
{
"url": "https://example.com",
"inputType": "DIRECT_URL"
}
```
**响应：** 包含风险评分、分类、重定向链、AI 总结和各引擎威胁结果的 `ScanResult` 对象。
### `GET /api/health`
返回所有已配置 API 后端的连接状态。
### `POST /api/admin/set-role`
在 Clerk 中设置用户的角色。受 `x-setup-key` 请求头保护，该请求头必须与 `SETUP_SECRET` 环境变量匹配。
## 项目结构
```
qr-guard/
├── api/ # Vercel serverless functions
│ ├── _utils.ts # Shared utilities (redirect chain, DNS, threat lookups)
│ ├── scan.ts # POST /api/scan
│ ├── health.ts # GET /api/health
│ └── admin/set-role.ts # POST /api/admin/set-role
├── src/
│ ├── App.tsx # Root component: routing, scan logic, pricing
│ ├── types.ts # Shared TypeScript types
│ ├── components/
│ │ ├── auth/ # Clerk auth modal + sandbox bypass
│ │ ├── dashboard/ # Landing page, scan history, usage stats
│ │ ├── results/ # Risk gauge, AI panel, threat detail widgets
│ │ └── scanner/ # QR drag-and-drop decoder, URL input form
│ └── pages/ # Admin, payment success/cancel pages
├── server.ts # Dev server (Express + Vite middleware)
├── vercel.json # Vercel deployment config
├── vite.config.ts
└── .env.example # Environment variable template
```
## 许可证
本项目基于 **Apache 2.0 License** 发布，您可以自由使用、修改和分发，但需注明出处。
[查看许可证](./LICENSE)