MCP Server Finder
P

YaraFlux

...
Created 3/6/2025byThreatFlux

Language:

Python

Stars:

9

Forks:

1

View on Github

YaraFlux MCP Server

GitHub release (latest by date) CI codecov Codacy Badge License: MIT Python Version FastAPI MCP Code style: black

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

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

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

# 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 is designed for seamless integration with Claude Desktop through the Model Context Protocol.

  1. Build the Docker image:
docker build -t yaraflux-mcp-server:latest .
  1. 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"
      ]
    }
  }
}
  1. 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:

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

🧪 Development

Local Development

# 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

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:

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

Last updated: 3/17/2025

Publisher info

ThreatFlux's avatar

ThreatFlux

ThreatFlux
1
followers
0
following
21
repos

More MCP servers built with Python

MCP-Collab

MCP Slack, Teams, WebEx

By sisodiabhumca
fulcra-context-mcp

Access your personal health data, sleep stats, location, calendar, and more securely through Context by Fulcra!

By fulcradynamics
alpaca-mcp-server

Alpaca MCP Servers deliver Alpaca’s Trading API best practices straight into your development and trading workflows.

By alpacahq