vaishk001/RealityCheck-AI
GitHub: vaishk001/RealityCheck-AI
融合本地 LLM、外部威胁情报与启发式规则的数字风险情报系统，用于实时检测钓鱼、诈骗和社会工程攻击。
Stars: 0 | Forks: 0
# RealityCheck AI – 数字风险情报系统
一个用于**诈骗、钓鱼和威胁检测**的全栈网络安全平台，由本地 LLM、外部威胁情报 API 和基于规则的风险引擎驱动。前端采用高级的 React + TailwindCSS，提供丰富的数据可视化，后端采用 Node.js/Express 并使用 MongoDB 进行持久化存储。
## 技术栈
### 后端
| 层级 | 技术 |
|---|---|
| 运行时 | Node.js (CommonJS) |
| 框架 | Express 4 |
| 数据库 | MongoDB + Mongoose |
| 本地 AI | Ollama (`llama3.1:8b`) |
| 威胁情报 | Google Safe Browsing API, VirusTotal API |
| 文件解析 | Multer, pdf-parse, mammoth, Tesseract.js (OCR) |
| 数据验证 | Joi |
| 安全 | Helmet, express-rate-limit, CORS |
### 前端
| 层级 | 技术 |
|---|---|
| 框架 | React 18 + Vite 5 |
| 样式 | TailwindCSS 3 |
| 动画 | Framer Motion 12 |
| 图标 | Lucide React |
| 路由 | React Router DOM 7 |
| HTTP | Axios |
## 项目结构
```
RealityCheckAI/
├── .env # Local environment variables (gitignored)
├── .env.example # Environment variable template
├── package.json # Backend dependencies & scripts
│
├── src/ # Backend source
│ ├── server.js # Entry point — starts HTTP server
│ ├── app.js # Express app setup (middleware, routes)
│ ├── config/
│ │ ├── db.js # MongoDB connection
│ │ └── env.js # Validated env config (via dotenv)
│ ├── controllers/
│ │ ├── scan.controller.js # Handles URL, text, file scan requests
│ │ ├── history.controller.js # Returns scan history
│ │ ├── status.controller.js # API health / status endpoint
│ │ └── threatReport.controller.js # Community threat report CRUD
│ ├── routes/
│ │ ├── scan.routes.js # POST /api/scan-url, /scan-text, /scan-file
│ │ ├── history.routes.js # GET /api/history
│ │ ├── status.routes.js # GET /api/status
│ │ └── threatReport.routes.js # POST/GET /api/report, /api/threats
│ ├── services/
│ │ ├── scan.service.js # Orchestrates the full scan pipeline
│ │ ├── ruleEngine.service.js # Heuristic / rule-based risk checks
│ │ ├── riskScoring.service.js # Aggregates signals → risk score (0–100)
│ │ ├── threatIntel.service.js # Google Safe Browsing + VirusTotal calls
│ │ ├── aiAnalyzer.service.js # Ollama LLM-based content analysis
│ │ ├── explanation.service.js # Generates human-readable explanations
│ │ ├── fileTextExtraction.service.js # PDF / DOCX / image OCR extraction
│ │ ├── history.service.js # Scan log persistence
│ │ ├── status.service.js # Ollama + DB health checks
│ │ └── threatReport.service.js # Community report persistence & voting
│ ├── models/
│ │ ├── ScanLog.model.js # Mongoose schema for scan results
│ │ └── ThreatReport.model.js # Mongoose schema for community reports
│ ├── middlewares/
│ │ ├── error.middleware.js # Global error handler
│ │ └── upload.middleware.js # Multer config for file uploads
│ └── utils/
│ ├── appError.js # Custom error class
│ ├── url.utils.js # URL parsing helpers
│ └── text.utils.js # Text normalisation helpers
│
└── web/ # Frontend source (React + Vite)
├── index.html
├── vite.config.js
├── tailwind.config.js
├── postcss.config.js
├── package.json # Frontend dependencies & scripts
└── src/
├── main.jsx # React entry point
├── App.jsx # Router — defines all page routes
├── index.css # Global styles / Tailwind base
├── lib/
│ └── api.js # Axios API client (base URL, helpers)
└── components/
├── LandingPage.jsx # Hero / marketing landing page
├── Dashboard.jsx # Main scanner dashboard shell
├── Scanner.jsx # Scan input form (URL / text / file tabs)
├── ResultDashboard.jsx # Full scan result display
├── ReportPage.jsx # Standalone full-page risk analysis report
├── Header.jsx # Global navigation header
├── AdvancedRiskGauge.jsx # Animated circular risk score gauge
├── HeatmapThreats.jsx # Threat category heatmap visualisation
├── HistoryPanel.jsx # Recent scan history list
├── HowItWorks.jsx # Explainer section (steps)
├── LiveScanSteps.jsx # Animated live scan progress steps
├── QuickTemplates.jsx # Pre-built quick-scan example templates
├── RiskTimeline.jsx # Timeline of risk signals
├── SignalRadar.jsx # Radar chart of threat signal categories
└── ThreatsPanel.jsx # Detailed breakdown of detected threats
```
## 环境变量
将 `.env.example` 复制为 `.env` 并填入相应的值：
```
PORT=4000
NODE_ENV=development
MONGO_URI=mongodb://127.0.0.1:27017/realitycheck_ai
# 威胁情报
GOOGLE_SAFE_BROWSING_API_KEY=
VIRUSTOTAL_API_KEY=
# 通过 Ollama 的本地 LLM
OLLAMA_BASE_URL=http://127.0.0.1:11434
OLLAMA_MODEL=llama3.1:8b
OLLAMA_ENABLED=true
OLLAMA_TIMEOUT_MS=15000
```
## 安装与运行
### 前置条件
- Node.js 18+
- MongoDB (本地或 Atlas)
- [Ollama](https://ollama.com/) 并已拉取 `llama3.1:8b` 模型 (`ollama pull llama3.1:8b`)
### 1. 后端
```
# 从项目根目录
cp .env.example .env # fill in API keys and MONGO_URI
npm install
npm run dev # starts with --watch (auto-restarts on save)
```
后端默认运行在 **http://localhost:4000**。
### 2. 前端
```
cd web
npm install
npm run dev
```
前端默认运行在 **http://localhost:5173** (已配置代理至后端)。
## API 参考
### 扫描端点
| 方法 | 路径 | 描述 |
|--------|------|-------------|
| `POST` | `/api/scan-url` | 扫描 URL 是否包含钓鱼/恶意软件 |
| `POST` | `/api/scan-text` | 扫描自由格式文本中的诈骗信号 |
| `POST` | `/api/scan-file` | 上传并扫描文件 (PDF, DOCX, 图像) |
| `GET` | `/api/history` | 获取最近的扫描日志 (`?limit=20`) |
| `GET` | `/api/status` | 健康检查 — 数据库和 Ollama 状态 |
#### POST /api/scan-url
```
// Request
{ "url": "https://suspicious-site.example.com" }
// Response
{
"score": 84,
"status": "Dangerous",
"reasons": [
"Flagged by VirusTotal (malicious: 4, suspicious: 2)",
"Google Safe Browsing: MALWARE",
"Unusual URL length with encoded characters"
],
"aiAnalysis": "...",
"explanation": "..."
}
```
#### POST /api/scan-text
```
// Request
{ "text": "URGENT! Your account has been compromised. Verify now at bit.ly/xyz" }
// Response — same shape as /scan-url
```
#### POST /api/scan-file
- `multipart/form-data`，字段名为 `file`
- 接收类型：PDF, DOCX, PNG, JPG (通过 Tesseract.js 进行 OCR)
- 响应 — 结构与上述相同
### 社区威胁报告
| 方法 | 路径 | 描述 |
|--------|------|-------------|
| `POST` | `/api/report` | 提交社区威胁报告 |
| `GET` | `/api/threats` | 列出所有社区报告的威胁 |
| `POST` | `/api/threats/:id/vote` | 对威胁报告进行赞成/反对投票 |
## 前端路由
| 路由 | 组件 | 描述 |
|-------|-----------|-------------|
| `/` | `LandingPage` | 带有功能亮点展示的营销落地页 |
| `/app` | `Dashboard` | 交互式扫描仪仪表板 |
| `/report` | `ReportPage` | 全页面的详细风险分析报告 |
| `*` | 重定向 → `/` | 兜底重定向 |
## 扫描流水线 (工作原理)
1. **接收输入** — URL、文本或提取的文件内容
2. **规则引擎** (`ruleEngine.service.js`) — 启发式检查 (URL 模式、可疑关键词、熵分析等)
3. **威胁情报** (`threatIntel.service.js`) — 并发调用 Google Safe Browsing + VirusTotal
4. **AI 分析** (`aiAnalyzer.service.js`) — Ollama LLM 分析内容中潜在的复杂诈骗/钓鱼信号
5. **风险评分** (`riskScoring.service.js`) — 将所有信号汇总计算为 0–100 的风险分数
6. **解释生成** (`explanation.service.js`) — 生成通俗易懂的推理说明
7. **持久化存储** (`history.service.js`) — 将结果保存到 MongoDB 的 `ScanLog` 集合中
8. **响应返回** — 将完整的 JSON 结果返回给前端
## 附加文档
| 文件 | 内容 |
|------|----------|
| [`CHEATSHEET.md`](./CHEATSHEET.md) | 快速参考命令与模式 |
| [`COMPONENT_MAP.md`](./COMPONENT_MAP.md) | 详细的组件关系说明 |
| [`FEATURE_SHOWCASE.md`](./FEATURE_SHOWCASE.md) | 各 UI 组件的功能描述 |
| [`DELIVERY_SUMMARY.md`](./DELIVERY_SUMMARY.md) | 项目交付总结与里程碑日志 |
| [`PREMIUM_UI_UPGRADE.md`](./PREMIUM_UI_UPGRADE.md) | UI 升级决策与设计说明 |
| [`README_ADVANCED_UI.md`](./README_ADVANCED_UI.md) | 高级 UI 组件深入解析 |
| [`INDEX.md`](./INDEX.md) | 所有项目文档的主索引 |
标签：AI风险缓解, GNU通用公共许可证, MITM代理, MongoDB, Node.js, React, Syscalls, 威胁情报, 开发者工具, 本地大语言模型, 网络钓鱼检测, 自定义脚本