a-sarja/Revisor
GitHub: a-sarja/Revisor
Revisor 是一个分布式多引擎杀毒文件扫描 pipeline，通过整合 ClamAV、Yara 规则和 VirusTotal API 来自动化检测文件是否含有恶意内容。
Stars: 33 | Forks: 19
# Revisor — 安全的分布式多引擎杀毒文件扫描 Pipeline
[](https://opensource.org/licenses/MIT)
[](https://www.python.org/)
[](https://docs.docker.com/compose/)
[](https://aws.amazon.com/)
Revisor 是一个现代化、分布式且高度可扩展的多引擎杀毒扫描 pipeline，专为高准确性、高速度和平台无关的安全分析而设计。通过结合多种检测机制——基于特征码的 (ClamAV)、自定义规则集 (Yara) 以及基于信誉/多扫描器的云端 (VirusTotal)——Revisor 提供了抵御现代恶意软件和潜在不受欢迎应用程序 (PUA) 的强大第一道防线。
## 🌟 核心功能
* **多引擎检测**：利用 **ClamAV**、自定义/众包 **Yara** 规则以及 **VirusTotal API** 的综合能力进行全面文件分析。
* **异步微服务架构**：解耦的后端和扫描引擎通过 AWS S3 和 DynamoDB 协同工作，允许对单个组件进行轻松扩展。
* **安全至上设计**：上传的文件在接入时会进行压缩并使用密码保护 (`pyminizip`)，以防止意外执行并确保传输安全。
* **HTTPS 加密**：在前端 Web 服务器 (Apache) 和后端 API (Flask) 上全面支持 SSL/TLS 证书。
* **自动化报告**：汇总所有引擎的扫描结果，生成专业的 PDF 报告，并连同原始分析的 CSV/JSON 附件直接发送到用户的电子邮箱。
## 🏗️ 架构
Revisor 采用了去中心化、事件驱动的微服务模式：
```
┌──────────────────────┐
│ Frontend Web │
│ (Apache / HTTPS) │
└──────────┬───────────┘
│ (HTTPS POST /upload-file)
▼
┌──────────────────────┐
│ Backend API │
│ (Flask / HTTPS) │
└─────┬──────────┬─────┘
(Upload Zip) │ │ (Create File Record)
┌────────────────────┘ └─────────────────────┐
▼ ▼
┌──────────────────────┐ ┌──────────────────┐
│ AWS S3 │ │ AWS DynamoDB │
│ (revisorfiles-v2) │ │ (revisor_files) │
└──────────────────────┘ └──────────────────┘
▲ ▲ ▲
│ │ │
│ (Download/ │ (Upload Reports) │ (Fetch/Update Status)
│ Scan Sample) │ │
└────────────────┴──────────┬─────────────────────────┘
│
┌──────────────────┼──────────────────┐
▼ ▼ ▼
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ ClamAV │ │ VirusTotal │ │ Yara Rules │
│ Worker Agent │ │ Worker Agent │ │ Worker Agent │
└──────────────┘ └──────────────┘ └──────────────┘
│
▼
┌─────────────────────┐
│ Scan Status Monitor │
│ & Report Gen │
└──────────┬──────────┘
│
▼ (SMTP TLS)
┌─────────────────────┐
│ Email Notification │
│ (PDF / CSV / JSON)│
└─────────────────────┘
```
1. **接入**：用户通过 HTTPS 前端上传文件。
2. **锁定与上传**：后端对文件进行哈希处理 (SHA256)，将其打包成受密码保护的 zip 文件，上传到 S3 (`revisorfiles-v2`)，并在 DynamoDB (`revisor_files`) 中注册扫描任务。
3. **解耦扫描**：各个扫描 worker (ClamAV、Yara 和 VirusTotal) 轮询 DynamoDB 获取待处理的扫描任务，从 S3 下载 zip 文件，使用共享密码进行解压，运行分析，将结果上传至 S3，并标记其任务已完成。
4. **汇总与交付**：扫描状态监控器在所有三个引擎完成后收集所有结果，生成 PDF 摘要报告，并将其通过电子邮件发送给用户。
## 📁 仓库结构
```
.
├── backend/ # Flask REST API server, database utils, and email notifier
│ ├── aws_dynamodb_utils.py # AWS DynamoDB integration
│ ├── aws_s3_utils.py # AWS S3 file upload/download utilities
│ ├── email_utils.py # PDF & attachment email service
│ ├── file_utils.py # Archiving and temp file handling
│ ├── report_gen.py # PDF report compiler using ReportLab
│ ├── scan_status_monitor.py# Scanner monitor and dispatch coordinator
│ └── revisor.py # Flask app server entrypoint
├── frontend/ # Client UI built with HTML5, CSS3, JS, and nicepage
│ ├── upload-api-service.js # Frontend script communicating with backend
│ └── index.html # Main file upload landing page
├── clamav_engine/ # ClamAV scanning integration worker
├── virus_total_integration/ # VirusTotal cloud scanning integration worker
├── yara_integration/ # Custom & crowdsourced Yara rules scanning worker
├── config/ # Configuration directory for AWS and SSL keys
│ ├── aws/ # Target folder for AWS config and credentials files
│ └── certs/ # Target folder for frontend and backend SSL certificates
├── docker_files/ # Service Dockerfiles and Docker Compose configuration
└── docs/ # Additional project documents and scanner logs
```
## 🚀 快速开始
### 📋 前置条件
在部署 Revisor 之前，请确保您具备以下条件：
* 已安装 **Docker 和 Docker Compose**。
* **AWS 凭证**：具有 AWS S3 和 AWS DynamoDB 访问权限的 IAM 用户。
* **AWS 资源**：
* 名为 `revisorfiles-v2` 的 S3 存储桶。
* 名为 `revisor_files` 且分区键为 `id` (String) 的 DynamoDB 表。
* **VirusTotal API Key**：在 [VirusTotal](https://www.virustotal.com/) 注册并获取您的 API key。
* **用于 SMTP 的电子邮件账户**：一个电子邮件账户（例如 Gmail）以及配置用于发送报告邮件的 App Password。
### 🔧 设置与配置
请按照以下步骤配置并构建应用程序技术栈：
#### 1. 设置 AWS 凭证
如果目录 `config/aws` 不存在，请创建它，并添加以下两个文件：
* **`config/aws/config`**：
[default]
region = us-east-2
* **`config/aws/credentials`**：
[default]
aws_access_key_id = YOUR_AWS_ACCESS_KEY_ID
aws_secret_access_key = YOUR_AWS_SECRET_ACCESS_KEY
*注意：这些文件将被复制到后端、ClamAV、Yara 和 VirusTotal 容器内的 `/root/.aws` 目录中，以启用对 S3 和 DynamoDB 的编程访问。*
#### 2. 生成 SSL/TLS 证书
为前端和后端服务器生成自签名的 SSL 证书密钥对。
* **后端证书**：
mkdir -p config/certs/backend
openssl req -new -x509 -keyout config/certs/backend/server.pem -out config/certs/backend/cert.pem -days 365 -nodes
* **前端证书**：
mkdir -p config/certs/frontend
openssl req -new -x509 -keyout config/certs/frontend/server.key -out config/certs/frontend/server.crt -days 365 -nodes
#### 3. 更新 Yara 规则
通过克隆目标规则库来初始化众包的 Yara 规则数据库：
```
cd yara_integration
python3 yara_rules_download.py
```
*（要在稍后更新您克隆的 Yara 规则，请运行 `python3 yara_rules_update.py`）*
#### 4. 配置环境变量
打开 `docker_files/docker-compose.yaml` 并更新环境变量的值：
* **后端服务**：
* `REVISOR_EMAIL`：发送扫描报告的电子邮件地址。
* `REVISOR_EMAIL_PASSWORD`：发送邮件账户的 App Password。
* **VirusTotal 服务**：
* `VT_API_KEY`：您的 VirusTotal API Key。
* **ClamAV REST API 服务 (CRA)**：
* `CLAMD_IP`：运行 Docker 的宿主机的 IP 地址（用于 ClamAV REST API 通信）。
### 📦 运行容器
要构建镜像并在后台启动完整的技术栈，请导航至 docker 文件目录并运行：
```
cd docker_files
docker-compose up --build -d
```
要停止所有服务：
```
docker-compose down
```
## 🔌 API 参考
### 1. 欢迎 & 初始化器
* **Endpoint**：`GET /`
* **端口**：`5000`
* **描述**：验证 API 后端健康状况并初始化后台 `scan_status_monitor` worker 进程。
* **响应**：
{
"code": 1000,
"message": "Welcome to Revisor - The Next Generation AV Engine!"
}
### 2. 上传文件进行扫描
* **Endpoint**：`POST /upload-file`
* **端口**：`5000`
* **Headers**：`Content-Type: multipart/form-data`
* **参数**：
* `user_file` (文件，必填)：要扫描的目标文件（必须小于 32 MB）。
* `user_email` (字符串，必填)：接收报告的电子邮件地址。
* **响应 (新文件)**：
{
"code": 1004,
"message": "File is successfully uploaded and sent for scanning"
}
* **响应 (缓存文件)**：
{
"code": 1004,
"message": "File already in the database",
"report": "..."
}
## 📊 应用程序界面
### 文件上传仪表板
用于上传文件和输入通知电子邮件地址的安全前端仪表板。
### 电子邮件报告摘要
扫描完成后发送给用户的自动生成的 PDF 报告和 CSV/JSON 分析文件示例。
## 🤝 贡献者
* **[Namruth Reddy](https://www.linkedin.com/in/namruth-reddy/)** — [namruth@outlook.com](mailto:namruth@outlook.com)
* **[Abhiram Sarja](https://www.linkedin.com/in/asarja)** — [abhiramsarja@gmail.com](mailto:abhiramsarja@gmail.com)
* **[Prateek Vutkur](https://www.linkedin.com/in/prateek-vutkur/)**
* **[Alekhya Digumarthy](https://www.linkedin.com/in/alekhya-digumarthy/)**
## 📄 许可证
该项目基于 MIT 许可证授权。查看 [LICENSE](LICENSE) 文件了解更多信息。
标签：Ask搜索, ClamAV, DAST, VirusTotal, Web 安全测试, YARA, 云资产可视化, 微服务架构, 恶意软件分析, 文件扫描, 版权保护, 请求拦截, 逆向工具