Servidor MCP de YaraFlux

Lanzamiento de GitHub (última fecha) código decodificador Insignia de Codacy Licencia: MIT Versión de Python API rápida MCP Estilo de código: negro

Un servidor de Protocolo de Contexto de Modelo (MCP) para escaneo YARA, que proporciona a los LLM capacidades para analizar archivos con reglas YARA.

📋 Descripción general

El servidor MCP de YaraFlux permite a los asistentes de IA realizar análisis de amenazas basados en reglas de YARA mediante la interfaz estandarizada del Protocolo de Contexto de Modelo. El servidor integra el análisis de YARA con los asistentes de IA modernos, lo que facilita la gestión integral de reglas, el análisis seguro y el análisis detallado de resultados mediante una arquitectura modular.

Related MCP server: MCP Toolkit

🧩 Descripción general de la arquitectura

+------------------------------------------+
|              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 sigue una arquitectura modular que separa las preocupaciones entre:

Capa de integración MCP : gestiona la comunicación con los asistentes de IA
Capa de implementación de herramientas : implementa la funcionalidad de escaneo y gestión de YARA
Capa de abstracción de almacenamiento : proporciona opciones de almacenamiento flexibles
Integración de YARA Engine : aprovecha YARA para el escaneo y la gestión de reglas

Para obtener diagramas de arquitectura detallados, consulte la Documentación de arquitectura .

✨ Características

🔄 Arquitectura modular
- Separación limpia de la integración de MCP, la implementación de herramientas y el almacenamiento
- Análisis de parámetros estandarizados y manejo de errores
- Backend de almacenamiento flexible con opciones locales y S3/MinIO
🤖 Integración MCP
- 19 herramientas MCP integradas para una funcionalidad integral
- Optimizado para la integración con Claude Desktop
- Análisis directo de archivos desde dentro de las conversaciones
- Compatible con la última especificación del protocolo MCP
🔍 Escaneo YARA
- Escaneo de contenido de archivos y URL
- Información detallada del partido con contexto
- Almacenamiento y recuperación de resultados de escaneo
- Motor de escaneo con rendimiento optimizado
📝 Gestión de reglas
- Crear, leer, actualizar, eliminar reglas de YARA
- Validación de reglas con informes detallados de errores
- Importar reglas desde el repositorio de ThreatFlux
- Categorización por fuente (personalizada vs. comunitaria)
📊 Análisis de archivos
- Vista hexadecimal para análisis binario
- Extracción de cadenas con parámetros configurables
- Metadatos de archivo e información hash
- Carga y almacenamiento seguros de archivos
🔐 Funciones de seguridad
- Autenticación JWT para acceso a API
- Ejecución de contenedor no raíz
- Aislamiento de almacenamiento seguro
- Controles de acceso configurables

🚀 Inicio rápido

Uso de la imagen de 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

Instalación desde la fuente

# 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

🧩 Integración de escritorio de Claude

YaraFlux está diseñado para una integración perfecta con Claude Desktop a través del Protocolo de Contexto de Modelo.

Construya la imagen de Docker:

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

Agregar a la configuración de 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"
      ]
    }
  }
}

Reinicie Claude Desktop para activar el servidor.

🛠️ Herramientas MCP disponibles

YaraFlux expone 19 herramientas MCP integradas:

Herramientas de gestión de reglas

list_yara_rules : Lista de reglas YARA disponibles con opciones de filtrado
get_yara_rule : obtiene el contenido y los metadatos de una regla YARA específica
validate_yara_rule : Valida la sintaxis de la regla YARA con informes detallados de errores
add_yara_rule : Crea una nueva regla YARA
update_yara_rule : Actualizar una regla YARA existente
delete_yara_rule : Eliminar una regla YARA
import_threatflux_rules : Importar reglas desde el repositorio de GitHub de ThreatFlux

Herramientas de escaneo

scan_url : escanear contenido de una URL con reglas YARA especificadas
scan_data : escanea los datos proporcionados (codificados en base64) con las reglas especificadas
get_scan_result : recupera resultados detallados de un escaneo anterior

Herramientas de gestión de archivos

upload_file : Sube un archivo para analizarlo o escanearlo
get_file_info : Obtener metadatos sobre un archivo cargado
list_files : Lista de archivos cargados con paginación y ordenación
delete_file : Eliminar un archivo cargado
extract_strings : Extrae cadenas ASCII/Unicode de un archivo
get_hex_view : Obtener una vista hexadecimal del contenido del archivo
download_file : Descargar un archivo cargado

Herramientas de gestión de almacenamiento

get_storage_info : Obtener estadísticas de uso del almacenamiento
clean_storage : elimina archivos antiguos para liberar espacio de almacenamiento

📚 Documentación

La documentación completa está disponible en el directorio docs/ :

Diagramas de arquitectura : representación visual de la arquitectura del sistema
Análisis de código : estructura detallada del código y recomendaciones
Guía de instalación : instrucciones de configuración detalladas
Guía de uso de la CLI : documentación de la interfaz de línea de comandos
Referencia de API : puntos finales y uso de la API REST
Guía de reglas de YARA : creación y gestión de reglas de YARA
Integración MCP - Detalles de la integración del Protocolo de Contexto del Modelo
Gestión de archivos : capacidades de manejo de archivos
Ejemplos - Ejemplos de uso en el mundo real

🗂️ Estructura del proyecto

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

🧪 Desarrollo

Desarrollo local

# 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

Flujos de trabajo de CI/CD

Este proyecto utiliza GitHub Actions para la integración y la implementación continuas:

Pruebas CI : se ejecutan en cada solicitud de inserción y extracción a las ramas principal y de desarrollo
- Ejecuta pruebas, formateo, revisión de errores y verificación de tipos.
- Crea y prueba imágenes de Docker
- Carga informes de cobertura de pruebas a Codecov
Incremento automático de versión : incrementa automáticamente la versión al enviarla a la rama principal
- Se actualiza la versión en pyproject.toml, setup.py y Dockerfile
- Crea una etiqueta git para la nueva versión
Publicar versión : se activa después de un incremento automático de versión exitoso
- Crea imágenes de Docker para múltiples etapas
- Genera notas de lanzamiento a partir de confirmaciones de Git
- Crea una versión de GitHub con artefactos
- Publica imágenes de Docker en Docker Hub

Estos flujos de trabajo garantizan la calidad del código y automatizan el proceso de lanzamiento.

Comprobaciones de estado

Las siguientes comprobaciones de estado se ejecutan en solicitudes de extracción:

✅ Verificación de formato : garantiza que el código siga los estándares de formato Black e isort
✅ Verificación de pelusa : valida la calidad del código y el cumplimiento de los estándares de codificación
✅ Ejecución de pruebas : ejecuta el conjunto de pruebas completo para verificar la funcionalidad
✅ Informe de cobertura : garantiza una cobertura de prueba suficiente de la base de código

🌐 Documentación de la API

Documentación API interactiva disponible en:

Interfaz de usuario Swagger: http://localhost:8000/docs
ReDoc: http://localhost:8000/redoc

Para obtener documentación detallada de la API, consulte Referencia de API .

🤝 Contribuyendo

¡Agradecemos sus contribuciones! No dude en enviar una solicitud de incorporación de cambios.

Bifurcar el repositorio
Crea tu rama de funciones ( git checkout -b feature/amazing-feature )
Confirme sus cambios ( git commit -m 'Add some amazing feature' )
Empujar a la rama ( git push origin feature/amazing-feature )
Abrir una solicitud de extracción

📄 Licencia

Este proyecto está licenciado bajo la licencia MIT: consulte el archivo de LICENCIA para obtener más detalles.

YaraFlux MCP Server