💡项目简介
一个Yara在线扫描引擎，服务端全部由Python开发。由@Shutdown与@kolomina共同开发～
您可以使用我们的服务也可以自行托管。使用这个项目，您可以方便地将Yara扫描功能装载到您的软件上。
官方地址：https://api.hishutdown.cn/yara/v1
官方调试地址：https://api.hishutdown.cn/yara/v1/docs
💬架构简述
Level 1 服务层
前段部分，主要负责用户与数据库之间的查询请求。此层可独立于任何部分，仅需能与数据库交互即可。
Level 2 控制层
负责监听数据库；启动扫描线程。
Level 3 扫描层
负责扫描文件，并写入扫描结果到数据库。
🔀执行流程（大致）
新建扫描任务
客户端发送检测请求➡️服务器服务层分配任务ID➡️客户端获取状态信息➡️客户端上传文件（当需要时）➡️服务器服务层接收文件并标记任务状态➡️控制层为任务分配线程，启动扫描层➡️扫描层输出报告至数据库➡️完成
获取扫描结果
客户端请求结果地址➡️服务端读取数据库➡️返回结果到客户端➡️完成
📣请求接口
./task/add：申请新的扫描任务
方式：GET
参数：hash
需要提交文件的MD5值（ MD5值会在服务端被自动转为小写）。
https://api.hishutdown.cn/yara/v1/task/add?hash=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx返回：
{
"packageVersion": 1,
"time": int(time.time()),
"taskApply": {
"code": 0,
"message": "...",
"id": xxxxxxxx,
"timestamp": xxxxxxxx,
"hash": xxxxxxx
}
}| 项 | 类型 | 解释 |
| packageVersion | INT | 数据包版本 |
| time | INT | 数据包制作时的时间戳 |
| code | INT | 状态码。通常为0；出现异常为负值 |
| message | STRING | 提示信息 |
| id | INT | 任务标识码 |
| timestamp | INT | 此任务创建时的时间戳 |
| hash | STRING | 文件哈希 |
./task/status：查询任务当前状态
方式：GET
参数：id
需要提交申请任务时返回的任务标识码。
https://api.hishutdown.cn/yara/v1/task/status?id=xxxxxxxxxxxxxxxxxxx返回
{
"packageVersion": 1,
"time": xxxxxx,
"taskStatus": {
"code": 0,
"message": "...",
"status": xxx,
"id": xxxxx,
"hash": xxxxx,
"addTime": xxxxxx,
"endTime": xxxxx,
"matchs": [xxx,xxx,xxx],
"rule_version": xxx
}
}| 项 | 类型 | 解释 |
| packageVersion | INT | 数据包版本 |
| time | INT | 数据包制作时的时间戳 |
| code | INT | 状态码。通常为0；出现异常为负值 |
| message | STRING | 提示信息 |
| status | STRING | 任务状态： Created=任务已创建 NoFile=等待上传被测文件， InList=文件已接收，排队扫描中， Scanning=正在扫描， Done=已完成 |
| id | INT | 任务标识码 |
| hash | STRING | 文件MD5 |
| addTime | INT | 任务添加时间 |
| endTime | INT | 完成扫描事件 |
| matchs | ARRAY | 命中的规则 |
| rule_version | INT | 规则版本号 |
./file：上传被扫描文件
方式：POST
参数：id
需要提交申请任务时返回的任务标识码。
https://api.hishutdown.cn/yara/v1/file/?id=xxxxxxxxxxxxxxxxxxx返回：
正常情况只返回HTTP状态码| HTTP状态码 | 解释 |
| 201 | 成功 |
| 400 | 非法的提交信息 |
| 500 | 服务端发生了意料之外的错误 |
🔨自托管
必要准备
本程序依赖MySQL，请自行安装并配置相关环境，另外您需要自行初始化数据库。
表1：file
此表用于存储文件信息，所有文件的信息都会存储在此。
| 列 | 类型 |
|---|---|
| hash | char(32) |
| status | tinytext |
| matchs | text |
| rule_version | bigint |
| timestamp | int |
表2：task
此表用于存储用户申请的任务，记录任务对应的HASH值。
| 列 | 类型 |
|---|---|
| id | bigint |
| timestamp | int |
| hash | text |
一般方式部署
本软件前端后端分开，前后端没有任何关联，本质上它们只依赖数据库传递信息并完成各自的工作。您可以自己设计前端或者后端以适应您的业务需要。
Environments
良好的运行条件是稳定运行的基础。
- 本项目开发时使用Linux作为调试与开发环境，建议使用Linux以提高稳定性。
- 本软件需要使用Python驱动，请自行配置相关环境。
- 请使用
pip -r requirements.txt安装依赖的库。
Files&Directorys
您需要准备一些目录和文件，否则程序可能会出现致命错误或无法启动。
前端
- 目录
- 用户待扫描的文件的存放目录（需要和后端的是同一个）。
- 未编译的原始规则文件存放目录。
- 已编译的预编译规则文件存放目录。
- 文件
- version：存放在未编译的原始规则文件存放目录的名字为version的文件，内容为该规则的版本信息（要求：纯整数，例如20240229001）（存在原因请参见补充信息第3点）。
- version：存放在已编译的预编译规则文件存放目录的名字为version的文件，内容为该规则的版本信息（要求：纯整数，例如20240229001）（存在原因请参见补充信息第3点）。
后端
- 目录
- 用户待扫描的文件的存放目录（需要和前端的是同一个）。
Run
- 前端：使用
uvicorn Api:app --host '0.0.0.0' --port 80即可运行。 - 后端：使用
python PyFile.py即可运行。
Docker部署
前端
- Network
- 80：API服务端口。
- Mounts
- /app/setting.ini：配置文件位置。
- /app/scan_file：待扫描文件目录。
启动指令：'uvicorn' 'Api:app' '--host' '0.0.0.0' '--port' '80' '--root-path' '/yara/v1'
后端
- Network
- 无，但是也要允许网络连接以连接SQL。
- Mounts
- /app/setting.ini：配置文件位置。
- /app/scan_file：待扫描文件目录。
- /app/RuleOrigin：未编译的原始规则文件存放目录。
- /app/RuleCompiled：已编译的预编译规则文件存放目录。
启动指令：'python' './Controller.py'
😗补充信息
- 我们对文件上传没有做任何限制，建议使用反向代理并在例如Nginx中设置限制。
- 我们对请求频率没有做任何限制，小心被刷爆。
- 规则编译仅会在未编译规则文件夹中的version文件中的数值大于已编译规则文件夹中的version文件中的数值时进行。
- 已扫描过的文件不会再被扫描（未来会更新成当当前规则新于扫描时规则版本时重新扫描）。
