YaraFlux MCP-Server
Ein Model Context Protocol (MCP)-Server für YARA-Scans, der LLMs die Möglichkeit bietet, Dateien mit YARA-Regeln zu analysieren.
📋 Übersicht
Der YaraFlux MCP Server ermöglicht KI-Assistenten die Durchführung von YARA-regelbasierten Bedrohungsanalysen über die standardisierte Model Context Protocol-Schnittstelle. Der Server integriert YARA-Scanning mit modernen KI-Assistenten und unterstützt so umfassendes Regelmanagement, sicheres Scanning und detaillierte Ergebnisanalysen durch eine modulare Architektur.
🧩 Architekturübersicht
+------------------------------------------+
| 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 folgt einer modularen Architektur, die Belange trennt zwischen:
- MCP-Integrationsschicht : Bewältigt die Kommunikation mit KI-Assistenten
- Tool-Implementierungsebene : Implementiert die YARA-Scan- und Verwaltungsfunktionalität
- Speicherabstraktionsschicht : Bietet flexible Speicheroptionen
- YARA Engine Integration : Nutzt YARA für Scanning und Regelmanagement
Ausführliche Architekturdiagramme finden Sie in der Architekturdokumentation .
✨ Funktionen
- 🔄 Modulare Architektur
- Saubere Trennung von MCP-Integration, Tool-Implementierung und Speicherung
- Standardisiertes Parameter-Parsing und Fehlerbehandlung
- Flexibles Speicher-Backend mit lokalen und S3/MinIO-Optionen
- 🤖 MCP-Integration
- 19 integrierte MCP-Tools für umfassende Funktionalität
- Optimiert für die Claude Desktop-Integration
- Direkte Dateianalyse aus Konversationen heraus
- Kompatibel mit der neuesten MCP-Protokollspezifikation
- 🔍 YARA-Scannen
- Scannen von URLs und Dateiinhalten
- Detaillierte Spielinformationen mit Kontext
- Speicherung und Abruf von Scanergebnissen
- Leistungsoptimierte Scan-Engine
- 📝 Regelverwaltung
- YARA-Regeln erstellen, lesen, aktualisieren, löschen
- Regelvalidierung mit detaillierter Fehlerberichterstattung
- Importieren Sie Regeln aus dem ThreatFlux-Repository
- Kategorisierung nach Quelle (benutzerdefiniert vs. Community)
- 📊 Dateianalyse
- Hexadezimalansicht für die Binäranalyse
- String-Extraktion mit konfigurierbaren Parametern
- Dateimetadaten und Hash-Informationen
- Sicheres Hochladen und Speichern von Dateien
- 🔐 Sicherheitsfunktionen
- JWT-Authentifizierung für den API-Zugriff
- Nicht-Root-Containerausführung
- Sichere Speicherisolierung
- Konfigurierbare Zugriffskontrollen
🚀 Schnellstart
Docker-Image verwenden
# 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
Installation von der Quelle
# 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-Integration
YaraFlux ist für die nahtlose Integration mit Claude Desktop über das Model Context Protocol konzipiert.
- Erstellen Sie das Docker-Image:
docker build -t yaraflux-mcp-server:latest .
- Zur Claude Desktop-Konfiguration hinzufügen (
~/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"
]
}
}
}
- Starten Sie Claude Desktop neu, um den Server zu aktivieren.
YaraFlux stellt 19 integrierte MCP-Tools bereit:
- list_yara_rules : Listet verfügbare YARA-Regeln mit Filteroptionen auf
- get_yara_rule : Ruft den Inhalt und die Metadaten einer bestimmten YARA-Regel ab
- validate_yara_rule : Validiert die YARA-Regelsyntax mit detaillierter Fehlerberichterstattung
- add_yara_rule : Erstellen Sie eine neue YARA-Regel
- update_yara_rule : Aktualisieren Sie eine vorhandene YARA-Regel
- delete_yara_rule : Löscht eine YARA-Regel
- import_threatflux_rules : Importieren Sie Regeln aus dem ThreatFlux-GitHub-Repository
- scan_url : Scannen Sie Inhalte von einer URL mit angegebenen YARA-Regeln
- scan_data : Scannen Sie bereitgestellte Daten (Base64-codiert) mit angegebenen Regeln
- get_scan_result : Ruft detaillierte Ergebnisse eines vorherigen Scans ab
- upload_file : Laden Sie eine Datei zur Analyse oder zum Scannen hoch
- get_file_info : Metadaten zu einer hochgeladenen Datei abrufen
- list_files : Liste hochgeladener Dateien mit Seitennummerierung und Sortierung
- delete_file : Löscht eine hochgeladene Datei
- extract_strings : Extrahieren Sie ASCII/Unicode-Zeichenfolgen aus einer Datei
- get_hex_view : Hexadezimale Ansicht des Dateiinhalts abrufen
- download_file : Laden Sie eine hochgeladene Datei herunter
- get_storage_info : Speichernutzungsstatistik abrufen
- clean_storage : Entfernen Sie alte Dateien, um Speicherplatz freizugeben
📚 Dokumentation
Eine umfassende Dokumentation ist im Verzeichnis docs/ verfügbar:
🗂️ Projektstruktur
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
🧪 Entwicklung
Lokale Entwicklung
# 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-Workflows
Dieses Projekt verwendet GitHub Actions für kontinuierliche Integration und Bereitstellung:
- CI-Tests : Läuft bei jeder Push- und Pull-Anforderung an Haupt- und Entwicklungszweige
- Führt Tests, Formatierungen, Lint-Tests und Typprüfungen durch
- Erstellt und testet Docker-Images
- Lädt Testabdeckungsberichte zu Codecov hoch
- Automatische Versionserhöhung : Erhöht die Version automatisch beim Pushen in den Hauptzweig
- Aktualisiert die Version in pyproject.toml, setup.py und Dockerfile
- Erstellt Git-Tags für neue Versionen
- Release veröffentlichen : Ausgelöst nach erfolgreicher automatischer Versionserhöhung
- Erstellt Docker-Images für mehrere Phasen
- Generiert Versionshinweise aus Git-Commits
- Erstellt GitHub-Release mit Artefakten
- Veröffentlicht Docker-Images im Docker Hub
Diese Workflows gewährleisten die Codequalität und automatisieren den Release-Prozess.
Statusprüfungen
Die folgenden Statusprüfungen werden für Pull Requests ausgeführt:
- ✅ Formatüberprüfung : Stellt sicher, dass der Code den Black- und Isort-Formatierungsstandards entspricht
- ✅ Lint-Verifizierung : Validiert die Codequalität und die Einhaltung von Codierungsstandards
- ✅ Testausführung : Führt die vollständige Testsuite aus, um die Funktionalität zu überprüfen
- ✅ Abdeckungsbericht : Stellt eine ausreichende Testabdeckung der Codebasis sicher
🌐 API-Dokumentation
Interaktive API-Dokumentation verfügbar unter:
Eine ausführliche API-Dokumentation finden Sie in der API-Referenz .
🤝 Beitragen
Beiträge sind willkommen! Senden Sie gerne einen Pull Request.
- Forken Sie das Repository
- Erstellen Sie Ihren Feature-Zweig (
git checkout -b feature/amazing-feature ) - Übernehmen Sie Ihre Änderungen (
git commit -m 'Add some amazing feature' ) - Pushen zum Zweig (
git push origin feature/amazing-feature ) - Öffnen einer Pull-Anfrage
📄 Lizenz
Dieses Projekt ist unter der MIT-Lizenz lizenziert – Einzelheiten finden Sie in der Datei LICENSE .
💖 Spenden oder nach Funktionen fragen