YaraFlux MCP Server

# YaraFlux MCP Server [](https://github.com/ThreatFlux/YaraFlux/releases) [](https://github.com/ThreatFlux/YaraFlux/actions) [](https://codecov.io/gh/ThreatFlux/YaraFlux) [](https://app.codacy.com/gh/ThreatFlux/YaraFlux/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade) [](https://opensource.org/licenses/MIT) [](https://www.python.org/downloads/) [](https://fastapi.tiangolo.com/) [](https://docs.anthropic.com/claude/docs/model-context-protocol) [](https://github.com/psf/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](docs/architecture_diagram.md). ## ✨ 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 ```bash # 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 ```bash # 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: ```bash docker build -t yaraflux-mcp-server:latest . ``` 2. Add to Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`): ```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. 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/](docs/) directory: - [Architecture Diagrams](docs/architecture_diagram.md) - Visual representation of system architecture - [Code Analysis](docs/code_analysis.md) - Detailed code structure and recommendations - [Installation Guide](docs/installation.md) - Detailed setup instructions - [CLI Usage Guide](docs/cli.md) - Command-line interface documentation - [API Reference](docs/api.md) - REST API endpoints and usage - [YARA Rules Guide](docs/yara_rules.md) - Creating and managing YARA rules - [MCP Integration](docs/mcp.md) - Model Context Protocol integration details - [File Management](docs/file_management.md) - File handling capabilities - [Examples](docs/examples.md) - 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 # 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 ```bash # 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: - Swagger UI: http://localhost:8000/docs - ReDoc: http://localhost:8000/redoc For detailed API documentation, see [API Reference](docs/api.md). ## 🤝 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](LICENSE) file for details. ## 💖 Donate or Ask for Features - [Patreon](https://patreon.com/vtriple) - [PayPal](https://paypal.me/ThreatFlux)