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.

Related MCP server: OpenCTI MCP Server

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

1. Erstellen Sie das Docker-Image:

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

2. 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"
      ]
    }
  }
}

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

1. Forken Sie das Repository

2. Erstellen Sie Ihren Feature-Zweig ( git checkout -b feature/amazing-feature )

3. Übernehmen Sie Ihre Änderungen ( git commit -m 'Add some amazing feature' )

4. Pushen zum Zweig ( git push origin feature/amazing-feature )

5. Ö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

• Patreon

• PayPal