YaraFlux MCP-Server

GitHub-Version (aktuellste nach Datum) Codecov Codacy-Abzeichen Lizenz: MIT Python-Version FastAPI MCP Codestil: schwarz

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.

Related MCP server: MCP Toolkit

🧩 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.

🛠️ Verfügbare MCP-Tools

YaraFlux stellt 19 integrierte MCP-Tools bereit:

Regelverwaltungstools

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-Tools

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

Dateiverwaltungstools

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

Speicherverwaltungstools

get_storage_info : Speichernutzungsstatistik abrufen
clean_storage : Entfernen Sie alte Dateien, um Speicherplatz freizugeben

📚 Dokumentation

Eine umfassende Dokumentation ist im Verzeichnis docs/ verfügbar:

Architekturdiagramme – Visuelle Darstellung der Systemarchitektur
Codeanalyse – Detaillierte Codestruktur und Empfehlungen
Installationshandbuch - Detaillierte Einrichtungsanweisungen
CLI-Nutzungshandbuch – Dokumentation zur Befehlszeilenschnittstelle
API-Referenz – REST-API-Endpunkte und -Verwendung
YARA-Regelhandbuch – Erstellen und Verwalten von YARA-Regeln
MCP-Integration – Details zur Model Context Protocol-Integration
Dateiverwaltung – Funktionen zur Dateiverwaltung
Beispiele – Anwendungsbeispiele aus der Praxis

🗂️ 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:

Swagger-Benutzeroberfläche: http://localhost:8000/docs
ReDoc: http://localhost:8000/redoc

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 .

YaraFlux MCP Server