YaraFlux MCP 服务器
用于 YARA 扫描的模型上下文协议 (MCP) 服务器，为 LLM 提供使用 YARA 规则分析文件的功能。
📋 概述
YaraFlux MCP 服务器使 AI 助手能够通过标准化的模型上下文协议 (MCP) 接口执行基于 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 身份验证
- 非 root 容器执行
- 安全存储隔离
- 可配置的访问控制
🚀 快速入门
使用 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
```bash
# 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 无缝集成。
- 构建 Docker 镜像：
docker build -t yaraflux-mcp-server:latest .
- 添加到 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"
]
}
}
}
- 重新启动 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/目录中提供了全面的文档：
🗂️ 项目结构
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 标签
- 发布 Release ：版本自动增量成功后触发
- 为多个阶段构建 Docker 镜像
- 从 git 提交生成发行说明
- 使用工件创建 GitHub 版本
- 将 Docker 镜像发布到 Docker Hub
这些工作流程确保代码质量并使发布过程自动化。
状态检查
以下状态检查针对拉取请求运行：
- ✅格式验证：确保代码遵循 Black 和 isort 格式标准
- ✅ Lint 验证：验证代码质量和是否符合编码标准
- ✅测试执行：运行完整的测试套件以验证功能
- ✅覆盖率报告：确保代码库有足够的测试覆盖率
🌐 API 文档
交互式 API 文档可在以下位置获取：
有关详细的 API 文档，请参阅API 参考。
🤝 贡献
欢迎贡献代码！欢迎提交 Pull 请求。
- 分叉存储库
- 创建你的功能分支（
git checkout -b feature/amazing-feature ） - 提交您的更改（
git commit -m 'Add some amazing feature' ） - 推送到分支（
git push origin feature/amazing-feature ） - 打开拉取请求
📄 许可证
该项目根据 MIT 许可证获得许可 - 有关详细信息，请参阅LICENSE文件。
💖 捐赠或索取功能