项目介绍
YaraFlux MCP Server
一个用于YARA扫描的模型上下文协议（MCP）服务器，提供给大型语言模型（LLMs）分析文件的能力。
📋 概述
YaraFlux MCP Server 允许AI助手通过标准化的模型上下文协议接口执行基于YARA规则的威胁分析。该服务器集成了YARA扫描与现代AI助手，支持全面的规则管理、安全扫描以及详细的分析结果，通过模块化架构实现。
🧩 架构概述
+------------------------------------------+
| AI 助手 |
+--------------------+---------------------+
|
| 模型上下文协议
|
+--------------------v---------------------+
| YaraFlux MCP Server |
| |
| +----------------+ +---------------+ |
| | MCP 服务器 | | 工具注册表 | |
| +-------+--------+ +-------+-------+ |
| | | |
| +-------v--------+ +-------v-------+ |
| | YARA 服务 | | 存储层 | |
| +----------------+ +---------------+ |
| |
+------------------------------------------+
| |
+-----------------+ +---------------+
| YARA 引擎 | | 存储 |
| - 规则编译 | | - 本地文件系统|
| - 文件扫描 | | - MinIO/S3 |
+-----------------+ +---------------+
YaraFlux 遵循模块化架构，分离了以下关注点：
- MCP 集成层：处理与AI助手的通信
- 工具实现层：实现YARA扫描和管理功能
- 存储抽象层：提供灵活的存储选项
- YARA 引擎集成：利用YARA进行扫描和规则管理
对于详细的架构图，请参阅架构文档。
✨ 特性
-
🔄 模块化架构
- 清晰地分离了MCP集成、工具实现和存储
- 标准化的参数解析和错误处理
- 支持本地和S3/MinIO的灵活存储后端
-
🤖 MCP 集成
- 集成了19个MCP工具以实现全面的功能
- 优化了Claude Desktop的集成
- 在对话中直接分析文件
- 兼容最新的MCP协议规范
-
🔍 YARA 扫描
- URL和文件内容扫描
- 提供详细匹配信息及上下文
- 扫描结果的存储和检索
- 性能优化的扫描引擎
-
📝 规则管理
- 创建、读取、更新、删除YARA规则
- 规则验证并提供详细的错误报告
- 从ThreatFlux仓库导入规则
- 按来源分类（自定义 vs 社区）
-
📊 文件分析
- 十六进制视图用于二进制分析
- 可配置参数的字符串提取
- 文件元数据和哈希信息
- 安全的文件上传和存储
-
🔐 安全特性
- 使用JWT认证访问API
- 非root容器执行
- 安全的存储隔离
- 可配置的访问控制
🚀 快速开始
使用Docker镜像
# 拉取最新Docker镜像
docker pull threatflux/yaraflux-mcp-server:latest
# 运行容器
docker run -p 8000:8000 \
-e JWT_SECRET_KEY=your-secret-key \
-e ADMIN_PASSWORD=your-admin-password \
-e DEBUG=true \
threatflux/yaraflux-mcp-server:latest
### 从源码构建Docker镜像
```bash
# 克隆仓库
git clone https://github.com/ThreatFlux/YaraFlux.git
cd YaraFlux/
# 构建Docker镜像
docker build -t yaraflux-mcp-server:latest .
# 运行容器
docker run -p 8000:8000 \
-e JWT_SECRET_KEY=your-secret-key \
-e ADMIN_PASSWORD=your-admin-password \
-e DEBUG=true \
yaraflux-mcp-server:latest
从源码安装
# 克隆仓库
git clone https://github.com/ThreatFlux/YaraFlux.git
cd YaraFlux/
# 安装依赖项（需要Python 3.13+）
make install
# 运行服务器
make run
🧩 Claude Desktop 集成
YaraFlux 设计用于通过模型上下文协议与Claude Desktop无缝集成。
- 构建Docker镜像：
docker build -t yaraflux-mcp-server:latest .
- 添加到Claude Desktop配置（
~/Library/Application Support/Claude/claude_desktop_config.json）：
{
"mcpServers": {
"yaraflux-mcp-server": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"--env",
"JWT_SECRET_KEY=your-secret-key",
"--env",
"ADMIN_PASSWORD=your-admin-password",
"--env",
"DEBUG=true",
"--env",
"PYTHONUNBUFFERED=1",
"threatflux/yaraflux-mcp-server:latest"
],
"disabled": false,
"autoApprove": [
"scan_url",
"scan_data",
"list_yara_rules",
"get_yara_rule"
]
}
}
}
- 重启Claude Desktop以激活服务器。
🛠️ 可用的MCP工具
YaraFlux 提供了19个集成的MCP工具：
规则管理工具
- list_yara_rules：列出可用的YARA规则，并提供过滤选项
- get_yara_rule：获取特定YARA规则的内容和元数据
- validate_yara_rule：验证YARA规则语法，并提供详细的错误报告
- add_yara_rule：创建新的YARA规则
- update_yara_rule：更新现有的YARA规则
- delete_yara_rule：删除YARA规则
- import_threatflux_rules：从ThreatFlux GitHub仓库导入规则
扫描工具
- scan_url：使用指定的YARA规则扫描URL内容
- scan_data：扫描提供的数据（base64编码），使用指定的规则
- get_scan_result：检索先前扫描的详细结果
文件管理工具
- upload_file：上传文件进行分析或扫描
- get_file_info：获取已上传文件的元数据
- list_files：列出已上传文件，支持分页和排序
- delete_file：删除已上传文件
- extract_strings：从文件中提取ASCII/Unicode字符串
- get_hex_view：获取文件内容的十六进制视图
- download_file：下载已上传文件
存储管理工具
- get_storage_info：获取存储使用统计信息
- clean_storage：移除旧文件以释放存储空间
📚 文档
完整的文档位于docs/目录下：
- 架构图 - 系统架构的可视化表示
- 代码分析 - 详细的代码结构和建议
- 安装指南 - 详细的设置说明
- CLI 使用指南 - 命令行界面文档
- API 参考 - REST API 端点和使用方法
- YARA 规则指南 - 创建和管理YARA规则
- MCP 集成 - 模型上下文协议集成详情
- 文件管理 - 文件处理能力
- 示例 - 实际使用案例
🗂️ 项目结构
yaraflux_mcp_server/
├── src/
│ └── yaraflux_mcp_server/
│ ├── app.py # FastAPI 应用程序
│ ├── auth.py # JWT 认证和用户管理
│ ├── config.py # 配置设置加载器
│ ├── models.py # 请求/响应的Pydantic模型
│ ├── mcp_server.py # MCP 服务器实现
│ ├── utils/ # 工具函数包
│ │ ├── __init__.py # 包初始化
│ │ ├── error_handling.py # 标准化的错误处理
│ │ ├── param_parsing.py # 参数解析工具
│ │ └── wrapper_generator.py # 工具包装生成器
│ ├── mcp_tools/ # 模块化MCP工具包
│ │ ├── __init__.py # 包初始化
│ │ ├── base.py # 基础工具注册工具
│ │ ├── file_tools.py # 文件管理工具
│ │ ├── rule_tools.py # YARA规则管理工具
│ │ ├── scan_tools.py # 扫描工具
│ │ └── storage_tools.py # 存储管理工具
│ ├── storage/ # 存储实现包
│ │ ├── __init__.py # 包初始化
│ │ ├── base.py # 基础存储接口
│ │ ├── factory.py # 存储客户端工厂
│ │ ├── local.py # 本地文件系统存储
│ │ └── minio.py # MinIO/S3存储
│ ├── routers/ # API 路由定义
│ │ ├── __init__.py # 包初始化
│ │ ├── auth.py # 认证API路由
│ │ ├── files.py # 文件管理API路由
│ │ ├── rules.py # YARA规则管理API路由
│ │ └── scan.py # YARA扫描API路由
│ ├── yara_service.py # YARA规则管理和扫描
│ ├── __init__.py # 包初始化
│ └── __main__.py # CLI 入口点
├── docs/ # 文档
├── tests/ # 测试套件
├── Dockerfile # Docker配置
├── entrypoint.sh # 容器入口脚本
├── Makefile # 构建自动化
├── pyproject.toml # 项目元数据和依赖项
├── requirements.txt # 核心依赖项
└── requirements-dev.txt # 开发依赖项
🧪 开发
本地开发
# 设置开发环境
make dev-setup
# 运行测试
make test
# 代码质量检查
make lint
make format
make security-check
# 生成测试覆盖率报告
make coverage
# 运行开发服务器
make run
CI/CD 工作流
此项目使用GitHub Actions进行持续集成和部署：
-
CI 测试：在主分支和develop分支上的每次推送和拉取请求时运行
- 运行测试、格式化、linting 和类型检查
- 构建和测试Docker镜像
- 将测试覆盖率报告上传到Codecov
-
版本自动递增：在主分支上推送时自动递增版本
- 更新pyproject.toml、setup.py和Dockerfile中的版本
- 为新版本创建git标签
-
发布版本：在成功版本自动递增后触发
- 为多个阶段构建Docker镜像
- 从git提交生成发行说明
- 创建带有工件的GitHub发行版
- 将Docker镜像发布到Docker Hub
这些工作流确保了代码质量并自动化了发布过程。
状态检查
在拉取请求上运行以下状态检查：
- ✅ 格式验证：确保代码遵循Black和isort格式标准
- ✅ Lint验证：验证代码质量和遵守编码标准
- ✅ 测试执行：运行完整的测试套件以验证功能
- ✅ 覆盖率报告：确保代码库有足够的测试覆盖率
🌐 API 文档
交互式API文档可在以下位置找到：
- Swagger UI: http://localhost:8000/docs
- ReDoc: http://localhost:8000/redoc
对于详细的API文档，请参阅API参考。
🤝 贡献
欢迎贡献！请随意提交Pull Request。
- 分叉仓库
- 创建你的功能分支 (
git checkout -b feature/amazing-feature) - 提交更改 (
git commit -m '添加一些惊人的功能') - 推送到分支 (
git push origin feature/amazing-feature) - 打开Pull Request
📄 许可
本项目采用MIT许可 - 详情见LICENSE文件。