hybrid server
The server is able to function both locally and remotely, depending on the configuration or use case.
Integrations
Uses FastAPI to provide REST API endpoints for YARA scanning, rule management, and file operations, with interactive API documentation.
Allows importing YARA rules directly from the ThreatFlux GitHub repository to expand scanning capabilities.
Offers flexible storage options with MinIO/S3 integration for storing files, YARA rules, and scan results, providing an alternative to local storage.
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.
- Build the Docker image:
- Add to Claude Desktop config (
~/Library/Application Support/Claude/claude_desktop_config.json):
- 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.
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add some amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
📄 License
This project is licensed under the MIT License - see the LICENSE file for details.
💖 Donate or Ask for Features
This server cannot be installed
A Model Context Protocol server that enables AI assistants to perform YARA rule-based threat analysis on files and URLs, supporting comprehensive rule management and detailed scanning results.