YaraFlux

Un servidor MCP para escaneo YARA, que permite a los LLMs analizar archivos usando reglas YARA.

Documentación

Servidor MCP YaraFlux

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

📋 Descripción general

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

🧩 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 responsabilidades 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 YARA
Capa de abstracción de almacenamiento: Proporciona opciones de almacenamiento flexibles
Integración del motor YARA: Aprovecha YARA para el escaneo y la gestión de reglas

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

✨ Características

🔄 Arquitectura modular
- Separación clara de la integración MCP, la implementación de herramientas y el almacenamiento
- Análisis de parámetros y manejo de errores estandarizados
- 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 las conversaciones
- Compatible con la última especificación del protocolo MCP
🔍 Escaneo YARA
- Escaneo de contenido de URL y archivos
- Información detallada de coincidencias con contexto
- Almacenamiento y recuperación de resultados de escaneo
- Motor de escaneo optimizado para el rendimiento
📝 Gestión de reglas
- Crear, leer, actualizar y eliminar reglas YARA
- Validación de reglas con informes de error detallados
- Importación de reglas desde el repositorio 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 archivos e información de hash
- Carga y almacenamiento seguro de archivos
🔐 Características de seguridad
- Autenticación JWT para acceso a la API
- Ejecución de contenedores sin usuario root
- Aislamiento seguro del almacenamiento
- Controles de acceso configurables

🚀 Inicio rápido

Uso de la imagen 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 el código 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

Bloqueo de dependencias

Las imágenes Docker y el escaneo de vulnerabilidades de CI se instalan desde requirements-lock.txt y requirements-dev-lock.txt — bloqueos con hash compilados desde pyproject.toml (restringidos por requirements.txt). pyproject.toml es la única fuente de verdad para las dependencias: las de tiempo de ejecución bajo dependencies, las de desarrollo bajo el extra dev (pip install -e ".[dev]"). Después de cambiar las dependencias allí o en requirements.txt, regenere los bloqueos:

make lock-requirements

Confirme los archivos de bloqueo actualizados con su cambio; CI falla si se desvían de pyproject.toml.

🧩 Integración con Claude Desktop

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

Construya la imagen Docker:

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

Agregue 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 las 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 reglas YARA con informes de error detallados
add_yara_rule: Crea una nueva regla YARA
update_yara_rule: Actualiza una regla YARA existente
delete_yara_rule: Elimina una regla YARA
import_threatflux_rules: Importa reglas desde el repositorio de GitHub ThreatFlux

Herramientas de escaneo

scan_url: Escanea contenido desde una URL con reglas YARA especificadas
scan_data: Escanea datos proporcionados (codificados en base64) con reglas especificadas
get_scan_result: Recupera resultados detallados de un escaneo anterior

Herramientas de gestión de archivos

upload_file: Carga un archivo para análisis o escaneo
get_file_info: Obtiene metadatos sobre un archivo cargado
list_files: Lista archivos cargados con paginación y ordenamiento
delete_file: Elimina un archivo cargado
extract_strings: Extrae cadenas ASCII/Unicode de un archivo
get_hex_view: Obtiene la vista hexadecimal del contenido del archivo
download_file: Descarga un archivo cargado

Herramientas de gestión de almacenamiento

get_storage_info: Obtiene 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 de código detallada y recomendaciones
Guía de instalación - Instrucciones de configuración detalladas
Guía de uso de CLI - Documentación de la interfaz de línea de comandos
Referencia de API - Endpoints de la API REST y uso
Guía de reglas YARA - Creación y gestión de reglas YARA
Integración MCP - Detalles de integración del Protocolo de Contexto de 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, 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)

🧪 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 CI/CD

Este proyecto utiliza GitHub Actions para la integración y el despliegue continuos:

Pruebas de CI: Se ejecutan en cada push y pull request a las ramas main y develop
- Ejecuta pruebas, formato, linting y verificación de tipos
- Construye y prueba imágenes Docker
- Sube informes de cobertura de pruebas a Codecov
Autoincremento de versión: Incrementa automáticamente la versión en los pushes a la rama main
- 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 del autoincremento exitoso de versión
- Construye imágenes Docker para múltiples etapas
- Genera notas de versión a partir de los commits de git
- Crea una versión de GitHub con artefactos
- Publica imágenes Docker en Docker Hub

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

Verificaciones de estado

Las siguientes verificaciones de estado se ejecutan en las pull requests:

✅ Verificación de formato: Garantiza que el código sigue los estándares de formato de Black e isort
✅ Verificación de lint: Valida la calidad del código y el cumplimiento de los estándares de codificación
✅ Ejecución de pruebas: Ejecuta la suite completa de pruebas para verificar la funcionalidad
✅ Informe de cobertura: Garantiza una cobertura suficiente de pruebas del código base

🌐 Documentación de la API

Documentación interactiva de la API disponible en:

Swagger UI: http://localhost:8000/docs
ReDoc: http://localhost:8000/redoc

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

🤝 Contribuciones

¡Las contribuciones son bienvenidas! No dude en enviar una Pull Request.

Haga un fork del repositorio
Cree su rama de características (git checkout -b feature/amazing-feature)
Confirme sus cambios (git commit -m 'Add some amazing feature')
Haga push a la rama (git push origin feature/amazing-feature)
Abra una Pull Request

📄 Licencia

Este proyecto está licenciado bajo la Licencia MIT - consulte el archivo LICENSE para más detalles.