EclipseFdn/yara-rest
GitHub: EclipseFdn/yara-rest
基于 YARA-X 的轻量级文件扫描 HTTP 微服务，提供标准化 REST API 用于恶意特征检测与文件分析。
Stars: 0 | Forks: 0
# YARA REST
[](go.mod)
[](LICENSE.md)
[](Dockerfile)
一个使用 [YARA-X](https://virustotal.github.io/yara-x/) 规则扫描文件的内部 HTTP 服务。设计用于在反向代理之后或私有网络内使用。
## 功能
- **简单的 REST API** — 通过 multipart 表单上传文件，获取 JSON 结果
- **归档支持** — 自动解压并扫描 ZIP 归档文件
- **Zip 炸弹防护** — 可配置的文件数量、大小和解压限制
- **安全加固** — 非 root 用户、HTTP 超时、日志脱敏，兼容 OpenShift
- **完全可配置** — 所有限制和超时均可通过环境变量设置
- **健康检查** — 内置用于存活/就绪探针的端点
## 快速开始
```
# 使用 Docker 构建并运行
docker build -t yara-rest .
docker run -d -p 9001:9001 -v /path/to/rules:/rules:ro yara-rest
# 测试它
curl http://localhost:9001/health
curl -X POST -F "file=@archive.zip" http://localhost:9001/scan
```
## API
### `POST /scan`
上传文件进行 YARA-X 扫描。接受单个文件或 ZIP 归档文件。
```
# 扫描单个文件
curl -X POST -F "file=@suspicious.js" http://localhost:9001/scan
# 扫描 ZIP 归档文件（解压并扫描所有内容）
curl -X POST -F "file=@package.zip" http://localhost:9001/scan
```
**响应：**
```
{
"matches": [
{
"rule": "EICAR_Test_Signature",
"file": "eicar.txt",
"file_hash": "275a021bbfb6489e54d471899f7db9d1663fc695ec2fe2a2c4538aabf651fd0f",
"severity": "LOW",
"description": "Detects the EICAR antivirus test file"
}
],
"scanned_files": 1,
"scan_time_ms": 45
}
```
### `GET /health`
健康检查端点。就绪时返回 `200 OK`。
```
{"status": "ok", "rules_path": "/rules"}
```
## 配置
所有设置均可通过环境变量进行配置：
### 服务器设置
| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `PORT` | `9001` | HTTP 服务器端口 |
| `YARA_RULES_PATH` | `/rules` | 包含 `.yar` 文件的目录 |
| `LOG_LEVEL` | `info` | 日志级别（`info` 或 `debug`） |
### HTTP 超时
防止 slowloris 攻击和慢速客户端造成的资源耗尽。
| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `HTTP_READ_TIMEOUT_SECONDS` | `60` | 读取完整请求的最大时间 |
| `HTTP_WRITE_TIMEOUT_SECONDS` | `300` | 写入响应的最大时间 |
| `HTTP_IDLE_TIMEOUT_SECONDS` | `120` | keep-alive 连接的最大空闲时间 |
### 大小限制
| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `MAX_UPLOAD_SIZE_MB` | `512` | 最大上传大小（multipart 表单） |
| `MAX_EXTRACTED_SIZE_MB` | `1024` | 最大总解压大小 |
| `MAX_FILE_COUNT` | `100000` | 归档文件中的最大文件数量 |
| `MAX_SINGLE_FILE_MB` | `256` | 单个文件的最大大小 |
### 扫描设置
| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `SCAN_TIMEOUT_MINUTES` | `5` | YARA-X 扫描的最大时间 |
| `MAX_RECURSION` | `0` | 最大目录递归深度（0 = 无限制） |
## YARA-X 规则
将 `.yar` 或 `.yara` 文件放置在规则目录中。子目录将被递归扫描。
规则可以包含用于严重性和描述的元数据：
```
rule Example_Rule {
meta:
description = "Describes what this rule detects"
severity = "high"
strings:
$suspicious = "malicious_pattern"
condition:
$suspicious
}
```
## 开发
提供了一个 Makefile 用于执行常见任务：
```
make build # Build the binary
make test # Run unit tests
make test-verbose # Run tests with verbose output
make test-cover # Run tests with coverage report
make fmt # Format code
make vet # Run go vet
make clean # Remove build artifacts
```
### 从源代码构建
需要 Go 1.23+。YARA-X 仅在运行时（容器中）需要。
```
make build
YARA_RULES_PATH=./test ./yara-rest
```
### Docker / Podman
```
make docker-build # Build image
make docker-run # Run container
make docker-test # Build, run, and test
# 或使用 Podman
make podman-build
make podman-run
```
手动命令：
```
docker build -t yara-rest .
docker run -d -p 9001:9001 -v ./rules:/rules:ro yara-rest
```
## 部署
### OpenShift 兼容性
该容器遵循 **GID 0 模式** 以兼容 OpenShift：
- 文件归 `1001:0`（UID 1001，GID 0）所有
- 权限允许组写入（`ug+rwx`）
- 适用于 OpenShift 分配的随机 UID（始终为 GID 0）
### 文件系统要求
| 路径 | 访问权限 | 用途 |
|------|--------|---------|
| `/tmp/scans` | 读写 | 扫描工作区 |
| `/rules` | 只读 | YARA-X 规则 |
| `/app` | 只读 | 应用程序二进制文件 |
当 `/tmp/scans` 作为可写卷挂载时，支持**只读根文件系统**。
### 调整 `/tmp/scans` 大小
每次并发扫描都需要临时空间来存放上传的文件和解压后的内容：
```
tmp_size = (MAX_UPLOAD_SIZE_MB + MAX_EXTRACTED_SIZE_MB) × concurrent_scans
```
| 并发扫描数 | 卷大小 |
|------------------|-------------|
| 1 | 1.5 GB |
| 5 | 7 GB |
| 20 | 30 GB |
使用 **tmpfs**（基于内存）以提高性能，或者在 RAM 有限的高并发场景下使用**磁盘**。
### 资源限制
推荐的 Kubernetes/OpenShift 资源配置：
```
resources:
limits:
cpu: "2"
memory: "2Gi"
requests:
cpu: "500m"
memory: "512Mi"
securityContext:
allowPrivilegeEscalation: false
readOnlyRootFilesystem: true
runAsNonRoot: true
capabilities:
drop:
- ALL
```
对于只读根文件系统，请挂载一个可写卷用于扫描：
```
volumeMounts:
- name: scans
mountPath: /tmp/scans
volumes:
- name: scans
emptyDir: {}
```
### 资源指南
| 流量 | 内存 | CPU |
|---------|--------|-----|
| 低 | 512Mi | 0.5 |
| 高（20 个并发） | 2Gi+ | 2+ |
## 测试
### 单元测试
在本地运行测试套件（无需 YARA-X）：
```
make test # Run all tests
make test-cover # Generate coverage report
```
单元测试涵盖配置、HTTP 处理程序、ZIP 解压和输出解析。需要 YARA-X 的集成测试在本地运行时会自动跳过。
### 集成测试
在容器中运行完整的集成测试：
```
make docker-test
```
### 手动测试
包含一个测试规则，可检测 [EICAR 测试签名](https://www.eicar.org/)：
```
docker run -d --name yara-test -p 9001:9001 -v $(pwd)/test:/rules:ro yara-rest
curl http://localhost:9001/health
curl -X POST -F "file=@test.zip" http://localhost:9001/scan
docker rm -f yara-test
```
## 贡献
欢迎贡献！请随时提交 Pull Request。
## 许可证
本项目基于 EPL 2.0 许可证授权 — 详见 [LICENSE.md](LICENSE.md)。
标签：DAST, Docker容器化, EICAR测试, EVTX分析, Go语言, Go语言工具, HTTP服务, REST API, URL发现, Web截图, YARA, YARA-X, ZIP解压, 云资产可视化, 云资产清单, 威胁情报, 子域名暴力破解, 安全检测, 容器安全, 开发者工具, 恶意软件分析, 文件哈希, 文件扫描, 日志审计, 沙箱, 程序破解, 网络安全, 网络测绘, 网页爬虫, 自动化检测, 规则匹配, 请求拦截, 逆向分析, 逆向工程, 防Zip Bomb, 隐私保护