Debasish-Nayak-656/-Neurovirus-Scanner
GitHub: Debasish-Nayak-656/-Neurovirus-Scanner
一款基于 React 与 Flask 构建的恶意软件分析平台，集成了 ClamAV、YARA 及 VirusTotal 引擎以实现多维度的文件扫描与威胁情报评估。
Stars: 0 | Forks: 0
# 🛡️ NeuroVirus — 高级威胁情报平台
一个具有赛博朋克风格 UI 的全栈病毒/恶意软件扫描器，基于以下技术构建：
| 层级 | 技术 |
|-------|-----------|
| Frontend | React 18, Recharts, Axios |
| Backend | Python 3.12 + Flask |
| AV 引擎 | ClamAV (通过 `clamd`) |
| 规则引擎 | YARA 4.x |
| 威胁情报 | VirusTotal API v3 |
| 容器 | Docker + Docker Compose |
| Web 服务器 | Nginx (生产环境) |
## 📐 架构
```
Browser (React)
│ HTTP (upload + results)
▼
Nginx :80
│ /api/* proxied to Flask
▼
Flask Backend :5000
├── Magic-byte detection
├── Shannon entropy analysis
├── Suspicious string extraction
├── Network indicator extraction
├── PE header parser (Windows EXE/DLL)
├── ClamAV ──────────────► clamd :3310
├── YARA rule engine
└── VirusTotal API v3 ───► cloud
```
## 🚀 快速开始 — Docker（推荐）
### 前置条件
- Docker Desktop ≥ 24
- Docker Compose v2
### 1. 克隆并配置
```
git clone neurovirus
cd neurovirus
# 创建你的 env 文件
cp .env.example .env
```
编辑 `.env` 并添加您的 **VirusTotal API key**（可在 https://www.virustotal.com/gui/join-us 免费获取）。
### 2. 启动所有服务
```
docker compose up --build
```
### 3. 打开 UI
```
http://localhost:3000
```
后端 API 可通过 `http://localhost:5000/api` 访问。
## 🛠️ 本地开发（不使用 Docker）
### 后端
#### 要求
- Python 3.10+
- 已安装 ClamAV 并正在运行 `clamd`（macOS 上使用 `brew install clamav`，Ubuntu 上使用 `apt install clamav clamav-daemon`）
- 已安装 YARA（`pip install yara-python` 需要 `yara` 系统库）
```
cd backend
# 创建虚拟环境
python -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate
# 安装依赖
pip install -r requirements.txt
# 复制并编辑 env
cp ../.env.example .env
# 启动 ClamAV daemon (如果尚未运行)
# macOS: brew services start clamav
# Ubuntu: sudo systemctl start clamav-daemon
# 运行 Flask dev server
python run.py
# → http://localhost:5000
```
#### ClamAV 设置 (Ubuntu/Debian)
```
sudo apt update
sudo apt install clamav clamav-daemon
# 更新特征数据库
sudo freshclam
# 启动 daemon
sudo systemctl enable clamav-daemon
sudo systemctl start clamav-daemon
# 验证
clamdscan --ping
```
#### ClamAV 设置 (macOS)
```
brew install clamav
sudo cp /opt/homebrew/etc/clamav/freshclam.conf.sample /opt/homebrew/etc/clamav/freshclam.conf
# 编辑 freshclam.conf：删除 "Example" 行
sudo freshclam
brew services start clamav
```
### 前端
```
cd frontend
npm install
npm start
# → http://localhost:3000 (将 /api 代理到 localhost:5000)
```
## 🔌 API 参考
所有 endpoint 均带有 `/api` 前缀。
### `POST /api/scan`
上传一个或多个文件进行分析。
**请求：** `multipart/form-data`，包含字段 `files`（一个或多个）。
**响应：**
```
{
"scanned": 1,
"results": [
{
"scan_id": "abc123def456",
"timestamp": "2026-03-19T10:00:00Z",
"filename": "suspicious.exe",
"file_size": 204800,
"file_type_magic": "PE Executable",
"file_extension": "exe",
"hashes": {
"md5": "...",
"sha1": "...",
"sha256": "..."
},
"entropy": 7.432,
"threat_score": 85,
"threat_level": "CRITICAL",
"findings": [
{
"name": "ClamAV: Win.Trojan.GenericKD",
"detail": "ClamAV signature match",
"severity": "critical",
"category": "MALWARE"
}
],
"clamav": { "status": "FOUND", "signature": "Win.Trojan.GenericKD" },
"yara_matches": [...],
"virustotal": { "status": "FOUND", "detections": 42, "total_engines": 72 },
"suspicious_strings": [...],
"network_indicators": [...],
"pe_info": { "architecture": "x64 (64-bit)", "num_sections": 6, ... },
"scan_duration_ms": 1243,
"errors": []
}
]
}
```
### `GET /api/scan/`
通过 ID 获取之前的扫描结果。
### `DELETE /api/scan/`
删除扫描结果及其从磁盘上传的文件。
### `GET /api/history?limit=50`
列出最近的扫描记录（轻量级摘要，不包含完整详情）。
### `POST /api/quarantine`
将扫描过的文件移动到隔离文件夹。
**Body：** `{ "scan_id": "abc123def456" }`
### `GET /api/status`
返回所有扫描引擎的健康/可用状态。
```
{
"engine": "NeuroVirus v3.14.1",
"clamav": { "available": true, "version": "ClamAV 1.3.0" },
"yara": { "available": true, "rule_files": 2, "yara_version": "4.5.1" },
"virustotal": { "available": true, "key_configured": true }
}
```
## 🧬 YARA 规则
自定义 YARA 规则位于 `backend/yara_rules/`。在该目录下添加 `.yar` 或 `.yara` 文件并重启后端——它们会被自动加载。
包含的规则集：
- `malware_generic.yar` — Ransomware、Keyloggers、Process Injection、Anti-Debug、Crypto Miners、Backdoors、PowerShell 滥用、Packers、PHP Webshells、Mimikatz
- `network_threats.yar` — C2 模式、DNS 隧道、Tor 隐藏服务、数据外泄
引擎识别的规则元数据字段：
```
rule My_Rule {
meta:
description = "Human-readable description shown in UI"
severity = "critical" // critical | high | medium | low
category = "MALWARE"
strings:
...
condition:
...
}
```
## 🔍 扫描能力
| 检查项 | 方法 | 检测内容 |
|-------|--------|-----------------|
| 文件类型 | Magic bytes | 真实文件类型与声明的扩展名对比 |
| 哈希 | MD5 / SHA-1 / SHA-256 | 身份标识、去重、VT 查询 |
| 熵 | Shannon 算法 | 加壳/加密/混淆的内容 |
| 字符串 | 对可打印字节进行正则匹配 | 23 种可疑的 API / 命令模式 |
| PE 头 | 结构解析 | 架构、节、WX 页面、加壳器 |
| 网络 IOC | 正则表达式 | URL、IP、可疑 TLD（.onion, .tk …） |
| AV 签名 | ClamAV clamd | 数以百万计的已知恶意软件签名 |
| 自定义规则 | YARA 4.x | 行为与结构模式匹配 |
| 云端情报 | VirusTotal API v3 | 70+ AV 引擎，哈希查询 + 文件上传 |
| 隔离 | 文件系统 | 将标记的文件从 uploads/ 隔离到 quarantine/ |
## 📁 项目结构
```
neurovirus/
├── docker-compose.yml
├── .env.example
├── .gitignore
│
├── backend/
│ ├── Dockerfile
│ ├── requirements.txt
│ ├── run.py ← Flask entry point
│ ├── app/
│ │ ├── __init__.py ← App factory
│ │ ├── config.py ← All configuration
│ │ ├── routes.py ← REST API endpoints
│ │ └── scanner.py ← Core scan engine (900 lines)
│ ├── yara_rules/
│ │ ├── malware_generic.yar
│ │ └── network_threats.yar
│ ├── uploads/ ← Temporary scan storage (git-ignored)
│ └── quarantine/ ← Quarantined files (git-ignored)
│
└── frontend/
├── Dockerfile
├── nginx.conf
├── package.json
└── src/
├── index.js
├── App.js ← Main UI (cyberpunk React)
├── App.css ← Cyberpunk stylesheet
└── api.js ← Axios API client
```
## 🔒 安全说明
- **绝不要在没有适当的 secrets manager 的情况下在生产基础设施上运行此项目** —— 使用环境变量或 Docker secrets，切勿硬编码 API key。
- `uploads/` 文件夹会在执行 `DELETE /api/scan/` 时自动清理。考虑添加 cron 作业来清除旧文件。
- ClamAV 的数据库会通过 `freshclamd` 自动更新。在 Docker 中，它会在容器启动时更新。
- VirusTotal 免费层级：**4 次请求/分钟，500 次/天**。如果扫描大量文件，请进行限流。
- 隔离文件夹存储带有 `.quarantine` 扩展名的文件——它们不会被执行，但请将其视为真实的恶意软件处理。
- 对于生产环境，请为 Flask API 添加身份验证 middleware（JWT / API key）。
## 📦 依赖项摘要
### 后端 Python 包
| 包 | 用途 |
|---------|---------|
| `flask` | Web 框架 |
| `flask-cors` | 跨域 headers |
| `clamd` | ClamAV TCP socket 客户端 |
| `yara-python` | YARA 规则引擎绑定 |
| `requests` | VirusTotal HTTP 调用 |
| `python-magic` | libmagic MIME 检测（可选） |
### 前端 npm 包
| 包 | 用途 |
|---------|---------|
| `react` | UI 框架 |
| `axios` | HTTP 客户端 |
| `recharts` | 径向仪表盘 + 条形图 |
## 🐛 故障排除
**ClamAV 提示 "Connection refused"**
→ 确保 `clamd` 正在运行：`sudo systemctl status clamav-daemon`
→ 在 Docker 中：等待健康检查通过（首次运行最长可能需要 2 分钟）
**YARA 导入错误**
→ `pip install yara-python` 需要 YARA C 库。在 Ubuntu 上：`sudo apt install yara`
**VirusTotal 返回 404**
→ 文件哈希不在 VT 的数据库中。如果文件 ≤32 MB，它将被自动上传以进行分析。
**"No module named clamd"**
→ 在激活 virtualenv 的情况下，在 `backend/` 目录中运行 `pip install -r requirements.txt`。
## 📜 许可证
MIT — 可自由使用，但**绝不要使用此工具扫描您不拥有或无权扫描的文件**。
标签：ClamAV, DAST, Docker, Flask, React, Syscalls, Web 安全测试, YARA, 云资产可视化, 威胁情报, 安全防御评估, 开发者工具, 恶意软件分析, 文件扫描, 请求拦截, 逆向工具