YaraFlux MCP服务器
用于YARA扫描的模型上下文协议（MCP）服务器，为LLM提供使用YARA规则分析文件的能力。
📋 概述
YaraFlux MCP Server使AI助手能够通过标准化的模型上下文协议接口执行基于YARA规则的威胁分析。该服务器将YARA扫描与现代AI助手集成在一起，通过模块化架构支持全面的规则管理、安全扫描和详细的结果分析。
🧩 架构概述
+------------------------------------------+
| AI Assistant |
+--------------------+---------------------+
|
| Model Context Protocol
|
+--------------------v---------------------+
| YaraFlux MCP Server |
| |
| +----------------+ +---------------+ |
| | MCP Server | | Tool Registry | |
| +-------+--------+ +-------+-------+ |
| | | |
| +-------v--------+ +-------v-------+ |
| | YARA Service | | Storage Layer | |
| +----------------+ +---------------+ |
| |
+------------------------------------------+
| |
+-----------------+ +---------------+
| YARA Engine | | Storage |
| - Rule Compiling| | - Local FS |
| - File Scanning | | - MinIO/S3 |
+-----------------+ +---------------+YaraFlux遵循模块化架构，将以下关注点分开：
- MCP集成层：处理与AI助手的通信
- 工具实现层：实现YARA扫描和管理功能
- 存储抽象层：提供灵活的存储选项
- YARA发动机集成：利用YARA进行扫描和规则管理
有关详细的架构图，请参阅 架构文档.
✨ 特性
- 🔄 模块化架构
- MCP集成、工具实施和存储的清晰分离 - 标准化参数解析和错误处理 - 具有本地和S3/MinIO选项的灵活存储后端
- 🤖 MCP集成
- 19个集成MCP工具，功能全面 - 针对Claude Desktop集成进行了优化 - 从对话中直接分析文件 - 与最新的MCP协议规范兼容
- 🔍 YARA扫描
- URL和文件内容扫描 - 详细的匹配信息与上下文 - 扫描结果存储和检索 - 性能优化的扫描引擎
- 📝 规则管理
- 创建、读取、更新、删除YARA规则 - 带有详细错误报告的规则验证 - 从ThreatFlux存储库导入规则 - 按来源分类（自定义与社区）
- 📊 文件分析
- 二进制分析的十六进制视图 - 使用可配置参数进行字符串提取 - 文件元数据和哈希信息 - 安全的文件上传和存储
- 🔐 安全功能
- API访问的JWT身份验证 - 非根容器执行 - 安全存储隔离 - 可配置的访问控制
🚀 快速开始
使用Docker镜像
# Pull the latest Docker image
docker pull threatflux/yaraflux-mcp-server:latest
# Run the container
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
### Using Docker building from source
Clone the repository
git clone https://github.com/ThreatFlux/YaraFlux.git cd YaraFlux/
Build the Docker image
docker build -t yaraflux-mcp-server:latest .
Run the container
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
### 从源安装
Clone the repository
git clone https://github.com/ThreatFlux/YaraFlux.git cd YaraFlux/
Install dependencies (requires Python 3.13+)
make install
Run the server
make run
## 🧩 Claude桌面集成
YaraFlux旨在通过模型上下文协议与Claude Desktop无缝集成。
1. 构建Docker镜像：
docker build -t yaraflux-mcp-server:latest .
2. 添加到Claude桌面配置(`~/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" ] } } }
3. 重新启动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规则
- **删除yara_rule**：删除YARA规则
- **重要三流规则**：从ThreatFlux GitHub存储库导入规则
### 扫描工具
- **scan_url**：使用指定的YARA规则从URL扫描内容
- **扫描数据**：使用指定规则扫描提供的数据（base64编码）
- **get_scan_result**：从上次扫描中检索详细结果
### 文件管理工具
- **上传文件**：上传文件进行分析或扫描
- **获取_文件_信息**：获取有关上传文件的元数据
- **列表文件**：列出已上传的文件，并进行分页和排序
- **删除文件**：删除上传的文件
- **提取字符串**：从文件中提取ASCII/Unicode字符串
- **get_hex_view**：获取文件内容的十六进制视图
- **下载文件**：下载上传的文件
### 存储管理工具
- **get_storage_info**：获取存储使用统计信息
- **清洁存储**：删除旧文件以释放存储空间
## 📚 文档
综合文档可在 [docs/](docs/) 目录：
- [架构图](docs/architecture_diagram.md) -系统架构的可视化表示
- [代码分析](docs/code_analysis.md) -详细的代码结构和建议
- [安装指南](docs/installation.md) -详细的设置说明
- [CLI使用指南](docs/cli.md) -命令行界面文档
- [api参考](docs/api.md) -REST API端点和使用
- [YARA规则指南](docs/yara_rules.md) -创建和管理YARA规则
- [MCP集成](docs/mcp.md) -模型上下文协议集成详细信息
- [文件管理](docs/file_management.md) -文件处理能力
- [例子](docs/examples.md) -实际使用示例
## 🗂️ 项目结构
yaraflux_mcp_server/ ├── src/ │ └── yaraflux_mcp_server/ │ ├── app.py # FastAPI application │ ├── auth.py # JWT authentication and user management │ ├── config.py # Configuration settings loader │ ├── models.py # Pydantic models for requests/responses │ ├── mcp_server.py # MCP server implementation │ ├── utils/ # Utility functions package │ │ ├── __init__.py # Package initialization │ │ ├── error_handling.py # Standardized error handling │ │ ├── param_parsing.py # Parameter parsing utilities │ │ └── wrapper_generator.py # Tool wrapper generation │ ├── mcp_tools/ # Modular MCP tools package │ │ ├── __init__.py # Package initialization │ │ ├── base.py # Base tool registration utilities │ │ ├── file_tools.py # File management tools │ │ ├── rule_tools.py # YARA rule management tools │ │ ├── scan_tools.py # Scanning tools │ │ └── storage_tools.py # Storage management tools │ ├── storage/ # Storage implementation package │ │ ├── __init__.py # Package initialization │ │ ├── base.py # Base storage interface │ │ ├── factory.py # Storage client factory │ │ ├── local.py # Local filesystem storage │ │ └── minio.py # MinIO/S3 storage │ ├── routers/ # API route definitions │ │ ├── __init__.py # Package initialization │ │ ├── auth.py # Authentication API routes │ │ ├── files.py # File management API routes │ │ ├── rules.py # YARA rule management API routes │ │ └── scan.py # YARA scanning API routes │ ├── yara_service.py # YARA rule management and scanning │ ├── __init__.py # Package initialization │ └── __main__.py # CLI entry point ├── docs/ # Documentation ├── tests/ # Test suite ├── Dockerfile # Docker configuration ├── entrypoint.sh # Container entrypoint script ├── Makefile # Build automation ├── pyproject.toml # Project metadata and dependencies ├── requirements.txt # Core dependencies └── requirements-dev.txt # Development dependencies
## 🧪 发展
### 地方发展
Set up development environment
make dev-setup
Run tests
make test
Code quality checks
make lint make format make security-check
Generate test coverage report
make coverage
Run development server
make run
### CI/CD工作流程
本项目使用GitHub Actions进行持续集成和部署：
- **CI测试**：对主分支和开发分支的每个推送和拉取请求进行运行
- 运行测试、格式化、linting和类型检查
- 构建和测试Docker镜像
- 将测试覆盖率报告上传到Codecov
- **版本自动递增**：推送到主分支时自动递增版本
- 更新pyproject.toml、setup.py和Dockerfile中的版本
- 为新版本创建git标签
- **发布发布**：版本自动增量成功后触发
- 为多个阶段构建Docker镜像
- 从git提交生成发行说明
- 使用工件创建GitHub版本
- 将Docker镜像发布到Docker Hub
这些工作流程确保了代码质量，并使发布过程自动化。
### 状态检查
对拉取请求运行以下状态检查：
- ✅ **格式验证**：确保代码遵循Black和isort格式标准
- ✅ **棉绒验证**：验证代码质量和是否符合编码标准
- ✅ **测试执行**：运行完整的测试套件以验证功能
- ✅ **覆盖范围报告**：确保代码库有足够的测试覆盖率
## 🌐 API文档
交互式API文档可在以下网址获取：
- Swagger用户界面：http://localhost:8000/docs
- ReDoc ：http://localhost:8000/redoc
有关API的详细文档，请参阅 [api参考](docs/api.md).
## 🤝 贡献
欢迎投稿！请随时提交拉取请求。
1. 分叉存储库
1. 创建功能分支(`git checkout -b feature/amazing-feature`)
1. 提交您的更改(`git commit -m 'Add some amazing feature'`)
1. 推到分支(`git push origin feature/amazing-feature`)
1. 打开拉取请求
## 📄 许可证
此项目根据MIT许可证获得许可-请参阅 [许可证](LICENSE) 文件以获取详细信息。
## 💖 捐赠或索取功能
- [Patreon](https://patreon.com/vtriple)
- [贝宝](https://paypal.me/ThreatFlux)