mjroshanackthar/Cyber-Shield
GitHub: mjroshanackthar/Cyber-Shield
CyberShield 是一款 AI 驱动的众包威胁情报平台，通过浏览器扩展实现钓鱼与 UPI 欺诈实时检测、跨警局案件关联和区块链证据存证，专为基层网络警务场景设计。
Stars: 0 | Forks: 0
# 🛡️ CyberShield：众包威胁情报与防篡改证据日志
[](https://github.com/)
[](https://vitejs.dev/)
[](https://fastapi.tiangolo.com/)
[](https://soliditylang.org/)
[](https://hardhat.org/)
[](https://developer.chrome.com/docs/extensions/)
为 **Prakasam District Police Hackathon 2026** 开发，CyberShield 通过引入将普通公民与网络犯罪调查人员直接连接的主动双向防御 pipeline，实现了被动网络警务的现代化。
## 📖 目录
1. [项目结构](#-project-structure)
2. [技术栈与架构](#-tech-stack--architecture)
3. [快速开始设置（完整 Pipeline）](#-quick-start-setup-complete-pipeline)
- [步骤 1：本地区块链账本](#step-1-local-blockchain-ledger)
- [步骤 2：FastAPI 后端引擎](#step-2-fastapi-backend-engine)
- [步骤 3：警方指挥控制台](#step-3-police-command-console)
- [步骤 4：加载 Chrome 扩展](#step-4-load-chrome-extension)
4. [项目文档指南](#-project-documentation-guide)
5. [跨站点关联演练](#-cross-station-correlation-walkthrough)
6. [核心技术实现](#-core-technical-implementations)
7. [开发者指南与故障排除](#-developer-guidelines--troubleshooting)
## 📁 项目结构
代码库模块化为四个专门的子项目：
```
404 Vision/
│
├── blockchain/ # Smart contracts and Ethereum Localhost Node (Hardhat)
│ ├── contracts/ # Solidity contracts (CyberShieldRegistry & ShieldToken)
│ └── scripts/ # Deployment and testing scripts
│
├── backend/ # FastAPI threat engine and detection logic
│ ├── verifiers/ # Domain, UPI, QR, and ML/NLP classifiers
│ └── main.py # API controller and database integration
│
├── dashboard/ # Vite + React policing console and hotspot visualizer
│ ├── src/ # React components, timelines, and SVGs
│ └── public/ # Static assets and ABIs
│
└── extension/ # Manifest V3 extension (WhatsApp & Gmail content guards)
├── content.js # Reactive DOM observer and scanner
└── background.js # Navigation blocker and MetaMask interface
```
## 🏗️ 技术栈与架构
### 系统流程图
```
graph TD
A["WhatsApp Web / Gmail Chrome Extension"] -->|1. Real-time Sniff| B["FastAPI Threat API (Port 8090)"]
B -->|2. Multi-Signal Verify| C["AI Classifier / Domain / UPI / QR Engine"]
C -->|3. Cross-Ref| D[(Suspected Mule Database)]
B -->|4. Log Receipt / Auth| E["CyberShieldRegistry Smart Contract (Localhost 8545)"]
A -->|5. MetaMask Gas-Free Auth| F["ShieldToken Contract (ERC-20)"]
F -->|6. Mint 50 SHIELD reward| A
G["Vite React Dashboard (Port 5173)"] -->|7. Poll Alerts & Timelines| B
G -->|8. Fetch Blockchain Evidence| E
```
- **前端（Dashboard）：** React.js (Vite), TailwindCSS, Leaflet.js, SVG 热力图。
- **扩展（Guard）：** 原生 JS Content Scripts, Chrome WebNavigation API, Manifest V3。
- **后端（Engine）：** Python FastAPI, SQLAlchemy ORM, Web3.py, OpenCV。
- **Web3（Ledger）：** Solidity (0.8.20), Hardhat Node, MetaMask API (JSON-RPC)。
## 🚀 快速开始设置（完整 Pipeline）
按顺序执行以下步骤以搭建本地 CyberShield 环境：
### 前置条件
- [Node.js](https://nodejs.org/) (v18+)
- [Python](https://www.python.org/) (v3.10+)
- 浏览器中已安装 [MetaMask 钱包扩展](https://metamask.io/)。
### 步骤 1：本地区块链账本
该账本运行一个本地 Hardhat 节点，并部署智能合约以记录取证哈希。
1. 打开终端并导航至 blockchain 目录：
cd "404 Vision/blockchain"
2. 安装 npm 依赖：
npm install
3. 启动本地 Ethereum 节点（持续运行）：
npm run node
4. 打开一个**新**终端，并将智能合约部署到本地网络：
cd "404 Vision/blockchain"
npm run deploy:local
*注意：这将自动部署 `CyberShieldRegistry.sol` 和 `ShieldToken.sol`，并将其 ABI/地址直接导出到后端和 dashboard 目录。*
### 步骤 2：FastAPI 后端引擎
后端使用混合 AI 模型对报告进行分类，并扫描域名/UPI。
1. 导航至 backend 目录：
cd "404 Vision/backend"
2. 激活预创建的 Python 虚拟环境：
# 在 Windows (PowerShell) 上：
.\venv\Scripts\activate
# 在 macOS/Linux 上：
source venv/bin/activate
3. 安装/同步 python 依赖：
pip install -r requirements.txt
4. 启动 FastAPI 服务器（运行于 `http://localhost:8090`）：
python main.py
### 步骤 3：警方指挥控制台
这个 React 应用显示实时的警务信息流、地图可视化和报告。
1. 导航至 dashboard 目录：
cd "404 Vision/dashboard"
2. 安装依赖：
npm install
3. 运行开发服务器：
npm run dev
4. 在浏览器中打开 `http://localhost:5173`。
### 步骤 4：加载 Chrome 扩展
该浏览器扩展可拦截 WhatsApp/Gmail 中的威胁并发出安全警报。
1. 打开 Google Chrome 并导航至 `chrome://extensions/`。
2. 打开右上角的**开发者模式**。
3. 点击左上角的**加载已解压的扩展程序**。
4. 选择位于 `404 Vision` 项目根目录下的 `extension` 文件夹。
5. 在你的 MetaMask 浏览器扩展中：
- 点击网络下拉菜单，选择**添加网络** -> **手动添加网络**。
- **网络名称**：`Hardhat Localhost`
- **新 RPC URL**：`http://127.0.0.1:8545`
- **链 ID**：`31337`
- **货币符号**：`ETH`
- 保存并切换到该网络。
- 导入在步骤 1 中由 `npm run node` 命令输出的其中一个私钥，以导入一个预充值账户。
## 📄 项目文档指南
虽然本文件作为分步设置指南，但该项目还包含一份详尽的 [PROJECT_DOCUMENTATION.md](file:///c:/Users/locha/Downloads/404%20Vision%20%281%29/404%20Vision/PROJECT_DOCUMENTATION.md)，详细说明了合规检查清单和功能需求。
以下是核心功能区域与文件的映射关系：
- **金融欺诈验证**：在 `backend/verifiers/upi_verifier.py`（检查支付别名）和 `backend/mule_tracker.py`（与疑似骡子银行账户列表匹配）内部处理。
- **钓鱼检测与 DGA 分析**：在 `backend/verifiers/domain_verifier.py` 中使用香农熵算法和外部 RDAP WHOIS 年龄测试进行管理。
- **文本分类**：在 `backend/verifiers/classifier.py` 中构建，使用本地余弦相似度向量矩阵，并动态回退到 Google Gemini 模型。
- **Chrome 拦截器**：嵌入在 `extension/background.js` 和 `extension/content.js` 中，以动态标记风险页面并挂钩社交元素。
## 🔄 跨站点关联演练
该平台开箱即用地包含了一个模拟的多管辖区活动关联场景。数据库预置了五个相互关联的公民举报：
1. **Ongole 警局（案件 1）**：用户举报了一条要求向 `fraud123@ybl` 支付款项的可疑短信。
2. **Vijayawada 警局（案件 2）**：第二名用户收到了引用相同 `fraud123@ybl` 账号的相同信息。
- *结果*：警方控制台自动检测到匹配的标识符，并将案件 2 与案件 1 关联。
3. **Guntur 警局（案件 3）**：用户举报了指向域名 `sbi-login-fake.net` 的钓鱼邮件。
4. **Hyderabad 警局（案件 4）**：举报了一封包含相同链接的匹配邮件。
- *结果*：系统标记出 Guntur 和 Hyderabad 之间存在协同活动。
5. **Nellore 警局（案件 5）**：举报了一起包含唯一目标的孤立投资骗局。
- *结果*：保持未关联状态，被归类为孤立的本地事件。
## 🛠️ 核心技术实现
### 1. 域名仿冒（Typosquatting）验证
系统根据已注册的品牌域名评估链接的 Levenshtein 距离（例如，将 `sbl-card.com` 与 `sbi.co.in` 进行匹配）。它使用 token 边界规则跳过标准的 URL 标记（如 WhatsApp 的 `wa.me` 链接）。
### 2. 取证哈希
当公民的举报被保存上链时：
- 文本内容、链接和交易会被打包进 JSON payload 中。
- 基于此 payload 生成加密的 `SHA-256` 摘要。
- `CyberShieldRegistry.sol` 合约将目标、类别、证据哈希和举报人地址保存到 Ethereum 账本上。
### 3. 游戏化奖励
对于每一份被验证为唯一的举报，服务器会触发向公民的 MetaMask 地址铸造 **50 个 SHIELD token**（ERC-20）。
## 🔧 开发者指南与故障排除
- **Python 中的 ModuleNotFoundError**：如果遇到导入失败，请确保已激活虚拟环境：
.\venv\Scripts\activate
如果由于目录迁移导致 python 特定的包或二进制模块（`_pydantic_core` 或 `_psycopg`）仍然损坏，请运行：
pip install --force-reinstall -r requirements.txt
- **MetaMask “Nonce” 错误**：如果重启 Hardhat 节点，MetaMask 会记住与新区块链状态不匹配的交易记录。在 MetaMask 中，前往 **Settings** -> **Advanced** -> **Clear activity tab data** 以重置交易 nonce。
- **端口冲突**：确保端口 `8090` (FastAPI)、`5173` (Vite) 和 `8545` (Hardhat) 未被其他活跃服务占用。
标签：React, Syscalls, 区块链, 威胁情报, 开发者工具, 智能合约, 浏览器扩展, 网络反诈, 自定义脚本, 逆向工具