Сервер YaraFlux MCP
Сервер протокола контекста модели (MCP) для сканирования YARA, предоставляющий LLM возможность анализировать файлы с помощью правил YARA.
📋 Обзор
YaraFlux MCP Server позволяет помощникам ИИ выполнять анализ угроз на основе правил YARA через стандартизированный интерфейс Model Context Protocol. Сервер интегрирует сканирование YARA с современными помощниками ИИ, поддерживая комплексное управление правилами, безопасное сканирование и подробный анализ результатов через модульную архитектуру.
🧩 Обзор архитектуры
+------------------------------------------+
| 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 через протокол контекста модели.
- Создайте образ Docker:
docker build -t yaraflux-mcp-server:latest .
- Добавьте в конфигурацию 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"
]
}
}
}
- Перезапустите 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/ :
🗂️ Структура проекта
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 доступна по адресу:
Подробную документацию по API см. в Справочнике API .
🤝 Вклад
Вклады приветствуются! Пожалуйста, не стесняйтесь отправлять запрос на включение.
- Форк репозитория
- Создайте ветку функций (
git checkout -b feature/amazing-feature ) - Зафиксируйте свои изменения (
git commit -m 'Add some amazing feature' ) - Отправить в ветку (
git push origin feature/amazing-feature ) - Открыть запрос на извлечение
📄 Лицензия
Данный проект лицензирован по лицензии MIT — подробности см. в файле LICENSE .
💖 Пожертвуйте или попросите функции