Сервер YaraFlux MCP

Сервер протокола контекста модели (MCP) для сканирования YARA, предоставляющий LLM возможность анализировать файлы с помощью правил YARA.

📋 Обзор

YaraFlux MCP Server позволяет помощникам ИИ выполнять анализ угроз на основе правил YARA через стандартизированный интерфейс Model Context Protocol. Сервер интегрирует сканирование YARA с современными помощниками ИИ, поддерживая комплексное управление правилами, безопасное сканирование и подробный анализ результатов через модульную архитектуру.

Related MCP server: OpenCTI MCP Server

🧩 Обзор архитектуры

+------------------------------------------+
|              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 : обеспечивает связь с помощниками на базе искусственного интеллекта.

• Уровень реализации инструмента : реализует функции сканирования и управления 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

🧩 Интеграция Claude Desktop

YaraFlux разработан для бесшовной интеграции с 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 : Сканировать содержимое с URL-адреса с указанными правилами YARA

• 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:

• Тесты CI : запускаются при каждом запросе push и pull в основных и разрабатываемых ветках.

  • Выполняет тесты, форматирование, линтинг и проверку типов

  • Создает и тестирует образы Docker

  • Загружает отчеты о тестовом покрытии в Codecov

• Автоувеличение версии : автоматически увеличивает версию при отправке в основную ветку.

  • Обновляет версию в pyproject.toml, setup.py и Dockerfile

  • Создает тег git для новой версии

• Опубликовать релиз : срабатывает после успешного автоматического увеличения версии

  • Создает образы Docker для нескольких этапов

  • Создает заметки о выпуске из коммитов git

  • Создает релиз GitHub с артефактами

  • Публикует образы Docker в Docker Hub

Эти рабочие процессы обеспечивают качество кода и автоматизируют процесс выпуска.

Проверка статуса

При запросах на извлечение выполняются следующие проверки статуса:

• ✅ Проверка формата : гарантирует, что код соответствует стандартам форматирования Black и Isort

• ✅ Проверка Lint : проверяет качество кода и его соответствие стандартам кодирования.

• ✅ Выполнение теста : запускает полный набор тестов для проверки функциональности

• ✅ Отчет о покрытии : обеспечивает достаточное тестовое покрытие кодовой базы

🌐 API-документация

Интерактивная документация API доступна по адресу:

• Пользовательский интерфейс Swagger: http://localhost:8000/docs

• Передокументировать: 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 .

💖 Пожертвуйте или попросите функции

• Патреон

• PayPal