📌Overview

Purpose: To provide a Model Context Protocol (MCP) server that enables AI assistants to perform YARA rule-based threat analysis.

Overview: YaraFlux MCP Server seamlessly integrates YARA scanning capabilities with modern AI assistants, leveraging a modular architecture for effective rule management, secure scanning, and in-depth result analysis.

Key Features:

Modular Architecture: Facilitates a clean separation between MCP integration, tool implementation, and storage, enhancing maintainability and scalability.
MCP Integration: Supports 19 integrated tools optimized for AI assistant interactions, allowing direct file analysis within conversations.
YARA Scanning: Provides high-performance scanning of URLs and file content, delivering detailed match information and storing scan results for retrieval.
Rule Management: Enables full CRUD operations on YARA rules, including validation and import from community sources.
File Analysis: Offers features like hexadecimal viewing, string extraction, and secure file uploads, which aid in binary analysis.
Security Features: Implements robust security measures like JWT authentication, ensuring safe API access and storage isolation.

YaraFlux MCP Server

A Model Context Protocol (MCP) server for YARA scanning, providing LLMs with capabilities to analyze files with YARA rules.

📋 Overview

YaraFlux MCP Server enables AI assistants to perform YARA rule-based threat analysis through the standardized Model Context Protocol interface. The server integrates YARA scanning with modern AI assistants, supporting comprehensive rule management, secure scanning, and detailed result analysis through a modular architecture.

🧩 Architecture Overview

+------------------------------------------+
|              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 follows a modular architecture that separates concerns between:

MCP Integration Layer: Handles communication with AI assistants
Tool Implementation Layer: Implements YARA scanning and management functionality
Storage Abstraction Layer: Provides flexible storage options
YARA Engine Integration: Leverages YARA for scanning and rule management

✨ Features

Modular Architecture
- Clean separation of MCP integration, tool implementation, and storage
- Standardized parameter parsing and error handling
- Flexible storage backend with local and S3/MinIO options
MCP Integration
- 19 integrated MCP tools for comprehensive functionality
- Optimized for Claude Desktop integration
- Direct file analysis within conversations
- Compatible with latest MCP protocol specification
YARA Scanning
- URL and file content scanning
- Detailed match information with context
- Scan result storage and retrieval
- Performance-optimized scanning engine
Rule Management
- Create, read, update, delete YARA rules
- Rule validation with detailed error reporting
- Import rules from ThreatFlux repository
- Categorization by source (custom vs. community)
File Analysis
- Hexadecimal view for binary analysis
- String extraction with configurable parameters
- File metadata and hash information
- Secure file upload and storage
Security Features
- JWT authentication for API access
- Non-root container execution
- Secure storage isolation
- Configurable access controls

🚀 Quick Start

Using Docker Image

docker pull threatflux/yaraflux-mcp-server:latest

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

Building Docker Image From Source

git clone https://github.com/ThreatFlux/YaraFlux.git
cd YaraFlux/

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

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 from Source

git clone https://github.com/ThreatFlux/YaraFlux.git
cd YaraFlux/

make install

make run

🧩 Claude Desktop Integration

YaraFlux is designed for seamless integration with Claude Desktop through the Model Context Protocol.

Build the Docker image:

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

Add to Claude Desktop config (~/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"
      ]
    }
  }
}

Restart Claude Desktop to activate the server.

🛠️ Available MCP Tools

YaraFlux exposes 19 integrated MCP tools:

Rule Management Tools

list_yara_rules: List available YARA rules with filtering options
get_yara_rule: Get a specific YARA rule's content and metadata
validate_yara_rule: Validate YARA rule syntax with detailed error reporting
add_yara_rule: Create a new YARA rule
update_yara_rule: Update an existing YARA rule
delete_yara_rule: Delete a YARA rule
import_threatflux_rules: Import rules from ThreatFlux GitHub repository

Scanning Tools

scan_url: Scan content from a URL with specified YARA rules
scan_data: Scan provided data (base64 encoded) with specified rules
get_scan_result: Retrieve detailed results from a previous scan

File Management Tools

upload_file: Upload a file for analysis or scanning
get_file_info: Get metadata about an uploaded file
list_files: List uploaded files with pagination and sorting
delete_file: Delete an uploaded file
extract_strings: Extract ASCII/Unicode strings from a file
get_hex_view: Get hexadecimal view of file content
download_file: Download an uploaded file

Storage Management Tools

get_storage_info: Get storage usage statistics
clean_storage: Remove old files to free up storage space

📚 Documentation

Comprehensive documentation is available in the docs directory:

Architecture Diagrams - Visual representation of system architecture
Code Analysis - Detailed code structure and recommendations
Installation Guide - Detailed setup instructions
CLI Usage Guide - Command-line interface documentation
API Reference - REST API endpoints and usage
YARA Rules Guide - Creating and managing YARA rules
MCP Integration - Model Context Protocol integration details
File Management - File handling capabilities
Examples - Real-world usage examples

🗂️ Project Structure

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
│       │   ├── error_handling.py
│       │   ├── param_parsing.py
│       │   └── wrapper_generator.py
│       ├── mcp_tools/             # Modular MCP tools package
│       │   ├── __init__.py
│       │   ├── base.py
│       │   ├── file_tools.py
│       │   ├── rule_tools.py
│       │   ├── scan_tools.py
│       │   └── storage_tools.py
│       ├── storage/               # Storage implementation package
│       │   ├── __init__.py
│       │   ├── base.py
│       │   ├── factory.py
│       │   ├── local.py
│       │   └── minio.py
│       ├── routers/               # API route definitions
│       │   ├── __init__.py
│       │   ├── auth.py
│       │   ├── files.py
│       │   ├── rules.py
│       │   └── scan.py
│       ├── yara_service.py        # YARA rule management and scanning
│       ├── __init__.py
│       └── __main__.py            # CLI entry point
├── docs/                          # Documentation
├── tests/                         # Test suite
├── Dockerfile
├── entrypoint.sh
├── Makefile
├── pyproject.toml
├── requirements.txt
└── requirements-dev.txt

🧪 Development

Local Development

make dev-setup
make test
make lint
make format
make security-check
make coverage
make run

CI/CD Workflows

CI Tests: Tests, formatting, linting, type checking, Docker image builds, and uploads coverage reports on push and PR.
Version Auto-increment: Automatically increments version on pushes to main branch and tags releases.
Publish Release: Builds multi-stage Docker images, generates release notes, creates GitHub releases, and publishes Docker images.

Status Checks

Format Verification with Black and isort
Lint Verification
Test Execution
Coverage Report

🌐 API Documentation

Interactive API documentation available at:

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

🤝 Contributing

Contributions are welcome!

Fork the repository
Create your feature branch
Commit your changes
Push to the branch
Open a Pull Request

📄 License

This project is licensed under the MIT License.

YaraFlux