Somicool/CyberShield-AI

## 📖 概述 **CyberShield AI** 是一个端到端平台，旨在保护市民免受钓鱼/诈骗攻击，并为**网络犯罪警察**提供 AI 辅助的调查工具。它融合了**机器学习检测引擎**、**透明的基于规则和启发式算法的层**，以及用于自然语言解释的 **Google Gemini** — 然后将每个检测到的实体（域名、电子邮件、电话、加密货币钱包、Telegram 账号）链接到 **Neo4j 威胁情报图**中，以揭露隐藏在看似无关的投诉背后的有组织犯罪活动。 一个后端支撑**三个终端**： | 👥 市民门户 | 👮 警察指挥中心 | 🧩 浏览器扩展 | |---|---|---| | 检查链接/电子邮件/SMS/二维码，提交投诉，学习网络安全知识 | 实时威胁源、案件管理、AI 调查工作区、威胁图谱、数据分析 | 实时网站保护 & 一键举报 | ## ✨ 核心功能 - 🔍 **混合检测引擎** — 使用 ML 模型 + 透明的启发式算法 + Gemini AI 解释，针对 URL、电子邮件、SMS 和二维码进行检测。 - 🕸️ **威胁情报图谱 (Neo4j)** — 发现不同的投诉共享相同的钱包 / 域名 / Telegram 账号 → 通过二跳网络遍历呈现协同犯罪活动。 - 🧠 **AI 调查助手** — 一个严格基于案件真实数据的上下文感知聊天助手（会标明来源，数据缺失时会说*“不可用”*）。 - 🗂️ **调查工作区** — 单个界面提供：AI 简报、检测明细、WHOIS/DNS/SSL/GeoIP、关联实体、相关案件、时间线、警官笔记以及 PDF 导出。 - ⚖️ **CrimeGPT** — 为警官提供法律条款建议、判例法引用和文书起草，并带有审计追踪记录。 - 🧩 **CyberShield Guardian** — 一款 Manifest V3 浏览器扩展，可实时拦截恶意网站（扩展内部不含 AI — 它直接复用相同的后端）。 - 📊 **分析与热力图** — Recharts 仪表板 + 使用 Leaflet 地图绘制**真实**的地理定位主机 IP（绝不捏造数据）。 - 🔐 **基于角色的访问控制** — 市民 · 警察 · 管理员，在后端和前端均通过 JWT 强制执行。 ## 🏗️ 架构 ``` Citizens · Browser Extension · Police · Admins │ HTTPS · REST /api · JWT ┌───────────▼────────────┐ │ React Frontend │ Citizen Portal + Police Dashboard └───────────┬────────────┘ ┌───────────▼────────────┐ │ FastAPI Backend │ │ Auth · Detection · │ │ Investigation · │ │ Complaints · Incidents ·│ │ Copilot · CrimeGPT · │ │ Admin · Graph │ └───┬──────────┬─────────┬─┘ ┌───────▼──┐ ┌────▼──────┐ ┌▼─────────────┐ │PostgreSQL│ │ Neo4j │ │ Gemini API │ │ users, │ │ entity │ │ explanations │ │ incidents│ │ relationship│ │ & summaries │ │ complaints│ │ graph │ │ │ │ audit_logs│ └────────────┘ └──────────────┘ └──────────┘ ``` **为什么使用双数据库？** PostgreSQL 存储结构化记录（用户、事件、投诉、审计日志）；Neo4j 存储实体之间的*关系* — 这正是将孤立的报告转化为可见犯罪网络的关键。 ## 🧠 检测原理 ``` URL / Email / SMS / QR │ ▼ ┌──────────────────┐ ┌───────────────────────┐ ┌──────────────────────┐ │ ML Base Score │ + │ Heuristic Points │ → │ Gemini Explanation │ │ (scikit-learn) │ │ (transparent rules) │ │ (plain language) │ └──────────────────┘ └───────────────────────┘ └──────────────────────┘ │ │ ▼ ▼ Risk Score 0–100 → Threat Level (low/medium/high/critical) + Why it was flagged ``` - **URL 分类器** — 基于 **PhiUSIIL** 数据集（235,795 个 URL）训练的 RandomForest。*基于 Origin 的评分* + 受信任域名白名单，确保在 Google/YouTube/GitHub 等网站上的误报率接近于零。 - **文本分类器** — TF-IDF + 逻辑回归（SMS Spam Collection + 精选的现代诈骗样本），适用于电子邮件和 SMS。 - **启发式算法** — IP 字面量域名、可疑的 TLD、品牌假冒、`@`-混淆、缺少 HTTPS、外部密码表单等。 - **Gemini** — 仅*解释*确定性流水线已做出的决定 — 从而保持结果的可重复性并便于审计。 ### 📈 模型性能 | 模型 | 数据集 | 准确率 | 精确率 | 召回率 | F1 | |---|---|:---:|:---:|:---:|:---:| | **URL 钓鱼** | PhiUSIIL (235,795 个 URL) | **99.5%** | 99.4% | 99.8% | **0.996** | | **文本诈骗 (电子邮件/SMS)** | SMS Spam Collection + 补充数据 (约 5,199 行) | **97.6%** | 91.0% | 90.4% | **0.907** | ## 🖥️ 平台模块

👥 市民门户

- **诈骗检测** — 一个选项卡式工具，用于检测链接 / 电子邮件 / SMS / 二维码 - **报告网络犯罪** — 提交投诉；在后台自动附带 AI 风险摘要 - **我的投诉** — 通过参考编号 (`CMP-2026-XXXXXX`) 追踪状态 - **网络安全** — 宣传教育内容 - **CyberShield Guardian** — 扩展状态、实时统计、安装指南

👮 警察指挥中心

- **仪表板** — KPI、AI 情报源、高优先级案件、实时威胁源（自动刷新、过滤、搜索） - **案件** — 过滤/排序、状态工作流、警员分配、批量操作 - **调查工作区** — AI 简报、WHOIS/DNS/SSL/GeoIP、关联实体、相关案件、时间线、笔记、PDF 报告 - **威胁 / 情报图谱** — 交互式网络可视化 + AI 犯罪活动分析 - **AI 调查助手** & **CrimeGPT** — 调查与法律助手 - **分析** (Recharts) + **热力图** (Leaflet，真实地理定位 IP)

🧩 CyberShield Guardian (浏览器扩展, MV3)

- **实时保护** — 检查每个网站的 Origin；拦截高置信度的恶意网站，对不确定的网站发出警告 - **右键“使用 CyberShield AI 分析”** - **弹出式仪表板** — 风险、预测、置信度、AI 解释、本地历史记录 - **一键举报** — 复用投诉 API + 您的市民会话

🛠️ 管理

- 用户管理（角色、启用/禁用、重置密码） - **系统健康中心** — 实时检查 FastAPI、PostgreSQL、Neo4j、Gemini、Auth - 实际运行时间、平台 KPI 以及数据导出

## 🧰 技术栈 | 层级 | 技术 | |---|---| | **后端** | FastAPI · SQLAlchemy · Pydantic · JWT (python-jose) · Uvicorn | | **数据库** | PostgreSQL (记录) · Neo4j Aura (图谱) | | **AI / ML** | scikit-learn (RandomForest, TF-IDF + 逻辑回归) · Google Gemini | | **调查** | python-whois · dnspython · ssl · ip-api (GeoIP) | | **前端** | React 19 · Vite · Tailwind CSS · React Router · Recharts · Leaflet · react-force-graph-2d · react-markdown | | **扩展** | Chrome/Edge Manifest V3 (service worker · content scripts · popup) | ## 📁 项目结构 ``` CyberShield-AI/ ├── backend/ # FastAPI backend │ └── app/ │ ├── api/routes/ # auth, detection, incidents, complaints, copilot, crimegpt, admin │ ├── ml/ # ML models, feature extraction, heuristics, training scripts │ ├── services/ # detection, investigation, graph, explanation, copilot │ ├── models/ # SQLAlchemy models (user, incident, complaint, audit) │ └── main.py # app entrypoint ├── frontend/ # React + Vite + Tailwind (citizen portal + police dashboard) │ └── src/{pages,components,api,context,lib} ├── browser-extension/ # CyberShield Guardian (Manifest V3) └── docs/ # architecture notes, datasets ``` ## 🚀 快速开始 ### 前置条件 - Python 3.13, Node.js 18+ - PostgreSQL，一个 Neo4j Aura 实例，以及一个 Google Gemini API key ### 1) 后端 ``` cd backend python -m venv venv venv\Scripts\activate # Windows (macOS/Linux: source venv/bin/activate) pip install -r requirements.txt # 配置 secrets copy .env.example .env # then fill in DATABASE_URL, SECRET_KEY, GEMINI_API_KEY, NEO4J_* # 运行 python -m uvicorn app.main:app --reload --port 8000 ``` ### 2) 前端 ``` cd frontend npm install npm run dev # http://localhost:5173 ``` ### 3) 浏览器扩展 1. 打开 `chrome://extensions` → 启用**开发者模式** 2. **加载已解压的扩展程序** → 选择 `browser-extension/` 文件夹 3. 登录一次市民门户，以便扩展程序能代表您进行举报 ## 🔌 API 概览 | 方法 & 路径 | 用途 | |---|---| | `POST /api/detect` | 检测 URL / 电子邮件 / SMS（持久化事件记录 + AI 解释） | | `POST /api/detect/scan` | 快速、非持久化的 URL 检查（由扩展使用） | | `POST /api/detect/{id}/investigate` | WHOIS / DNS / SSL / GeoIP 信息补充 | | `GET /api/detect/graph/{type}/{value}` | 威胁图谱网络查询 | | `POST /api/complaints` | 提交市民投诉 | | `POST /api/copilot/chat` | 流式传输 AI 调查助手 | | `GET /api/incidents` · `/stats` · `/map/points` | 仪表板信息源、分析数据、热力图 | | `GET /api/admin/health` | 实时系统健康状态 | ## 📚 数据集 | 数据集 | 用途 | 规模 | 许可证 | |---|---|---|---| | [PhiUSIIL Phishing URL Dataset](https://archive.ics.uci.edu/dataset/967/phiusiil+phishing+url+dataset) | URL 分类器 | 235,795 个 URL | CC BY 4.0 | | [SMS Spam Collection](https://www.kaggle.com/datasets/uciml/sms-spam-collection-dataset) + 精选补充数据 | 电子邮件/SMS 分类器 | 约 5,199 行 | 仅供研究使用 | *引用：Prasad, A. & Chandra, S. (2024); Almeida, T.A., Gómez Hidalgo, J.M., & Yamakami, A. (2011).* ## 🔒 安全与隐私 - **JWT 身份验证**，具有三种角色（市民 / 警察 / 管理员），在后端和前端均强制执行。 - **bcrypt** 密码哈希加密；被禁用的账户无法登录。 - 密钥仅存在于 `backend/.env` 中（**已 gitignore，从不提交**）。 - 扩展**不存储任何密码**（它桥接 Web 会话 token）；浏览历史记录保留在**本地设备上**。 - AI 安全护栏：确定性评分、带来源归属的回答，且**绝不捏造**任何实体、关系或证据。 ## 🗺️ 路线图 - [ ] 外部威胁源（Google Safe Browsing / URLhaus） - [ ] 持续的实时健康监控与警报 - [ ] 证据保险库 & 监管链 - [ ] CERT-In / CCTNS 集成 - [ ] MFA / SSO / LDAP - [ ] 多语言 & 语音市民助手

标签：测试用例, 自定义脚本, 逆向工具