YaraFlux MCP Server

YaraFlux MCP Server

一个用于 YARA 扫描的模型上下文协议（MCP）服务，为大模型提供使用 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 仓库导入规则
  • 按来源（自定义规则或社区规则）分类

• 📊 文件分析

  • 通过十六进制视图分析二进制文件
  • 使用可配置参数提取字符串
  • 提供文件元数据和哈希信息
  • 安全地上传和存储文件

• 🔐 安全功能

  • 使用 JWT 验证 API 访问
  • 以非 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

依赖锁定

Docker 镜像和 CI 漏洞扫描会从 requirements-lock.txt 和 requirements-dev-lock.txt 安装依赖。这些锁定文件包含哈希固定的依赖版本，由 pyproject.toml 编译生成（并受 requirements.txt 约束）。pyproject.toml 是依赖项的 唯一事实来源：运行时依赖位于 dependencies 下，开发依赖位于 dev 扩展项下（pip install -e ".[dev]"）。在其中或 requirements.txt 中更改依赖项后，请重新生成锁定文件：

make lock-requirements

请将更新后的锁定文件与更改一并提交；如果它们与 pyproject.toml 不一致，CI 就会失败。

🧩 Claude Desktop 集成

YaraFlux 专为通过 Model Context Protocol 与 Claude Desktop 无缝集成而设计。

1. 构建 Docker 镜像：

docker build -t yaraflux-mcp-server:latest .

2. 添加到 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"
      ]
    }
  }
}

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 规则
• 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 集成 - Model Context Protocol 集成详情
• 文件管理 - 文件处理功能
• 示例 - 实际使用示例

🗂️ 项目结构

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, runtime deps, and the `dev` extra
├── requirements.txt               # Core dependency floors (also constrains the locks)
├── requirements-lock.txt          # Hash-pinned runtime lock (Docker build + security scan)
└── requirements-dev-lock.txt      # Hash-pinned runtime + dev lock (test image + security scan)

🧪 开发

本地开发

# 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 测试：每次向 main 和 develop 分支推送代码或提交拉取请求时运行

  • 运行测试、格式检查、代码检查和类型检查
  • 构建并测试 Docker 镜像
  • 将测试覆盖率报告上传到 Codecov

• 版本自动递增：向 main 分支推送代码时自动递增版本号

  • 更新 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 参考。

🤝 参与贡献

欢迎贡献！欢迎随时提交拉取请求。

1. 复刻此代码库
2. 创建功能分支（git checkout -b feature/amazing-feature）
3. 提交更改（git commit -m 'Add some amazing feature'）
4. 推送到该分支（git push origin feature/amazing-feature）
5. 创建拉取请求

📄 许可证

本项目采用 MIT 许可证授权，详情请参阅 LICENSE 文件。

💖 捐赠或提出功能需求

• Patreon
• PayPal