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

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

For detailed architecture diagrams, see the Architecture Documentation.

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

Installation from Source

🧩 Claude Desktop Integration

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

1. Build the Docker image:

2. Add to Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

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

🧪 Development

Local Development

CI/CD Workflows

This project uses GitHub Actions for continuous integration and deployment:

• CI Tests: Runs on every push and pull request to main and develop branches

  • Runs tests, formatting, linting, and type checking

  • Builds and tests Docker images

  • Uploads test coverage reports to Codecov

• Version Auto-increment: Automatically increments version on pushes to main branch

  • Updates version in pyproject.toml, setup.py, and Dockerfile

  • Creates git tag for new version

• Publish Release: Triggered after successful version auto-increment

  • Builds Docker images for multiple stages

  • Generates release notes from git commits

  • Creates GitHub release with artifacts

  • Publishes Docker images to Docker Hub

These workflows ensure code quality and automate the release process.

Status Checks

The following status checks run on pull requests:

• ✅ Format Verification: Ensures code follows Black and isort formatting standards

• ✅ Lint Verification: Validates code quality and compliance with coding standards

• ✅ Test Execution: Runs the full test suite to verify functionality

• ✅ Coverage Report: Ensures sufficient test coverage of the codebase

🌐 API Documentation

Interactive API documentation available at:

• Swagger UI: http://localhost:8000/docs

• ReDoc: http://localhost:8000/redoc

For detailed API documentation, see API Reference.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository

2. Create your feature branch (git checkout -b feature/amazing-feature)

3. Commit your changes (git commit -m 'Add some amazing feature')

4. Push to the branch (git push origin feature/amazing-feature)

5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

💖 Donate or Ask for Features

• Patreon

• PayPal