Servidor MCP de YaraFlux
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.
🧩 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/ :
🗂️ 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:
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.
💖 Dona o pide funciones