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/目录中提供了全面的文档：

架构图——系统架构的可视化表示
代码分析——详细的代码结构和建议
安装指南- 详细设置说明
CLI 使用指南- 命令行界面文档
API 参考- REST API 端点和用法
YARA 规则指南- 创建和管理 YARA 规则
MCP 集成- 模型上下文协议集成详情
文件管理- 文件处理功能
示例- 真实世界的使用示例

🗂️ 项目结构

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 文档可在以下位置获取：

Swagger 用户界面： http://localhost:8000/docs
ReDoc： http://localhost:8000/redoc

有关详细的 API 文档，请参阅API 参考。

🤝 贡献

欢迎贡献代码！欢迎提交 Pull 请求。

分叉存储库
创建你的功能分支（ git checkout -b feature/amazing-feature ）
提交您的更改（ git commit -m 'Add some amazing feature' ）
推送到分支（ git push origin feature/amazing-feature ）
打开拉取请求

📄 许可证

该项目根据 MIT 许可证获得许可 - 有关详细信息，请参阅LICENSE文件。

YaraFlux MCP Server

Integrations