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
Note: Code block was split into 2 parts due to size limits.
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
- Version Auto-increment: Automatically increments version on pushes to main branch
- Publish Release: Triggered after successful version auto-increment
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
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
Note: Code block was split into 2 parts due to size limits.
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
- Version Auto-increment: Automatically increments version on pushes to main branch
- Publish Release: Triggered after successful version auto-increment
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.