YaraFlux

Um servidor MCP para escaneamento YARA, permitindo que LLMs analisem arquivos usando regras YARA.

Documentação

Servidor MCP YaraFlux

Um servidor Model Context Protocol (MCP) para varredura YARA, fornecendo aos LLMs capacidades de analisar arquivos com regras YARA.

📋 Visão Geral

O Servidor MCP YaraFlux permite que assistentes de IA realizem análises de ameaças baseadas em regras YARA por meio da interface padronizada do Model Context Protocol. O servidor integra a varredura YARA com assistentes de IA modernos, suportando gerenciamento abrangente de regras, varredura segura e análise detalhada de resultados por meio de uma arquitetura modular.

🧩 Visão Geral da Arquitetura

+------------------------------------------+
|              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    |
 +-----------------+  +---------------+

O YaraFlux segue uma arquitetura modular que separa responsabilidades entre:

Camada de Integração MCP: Gerencia a comunicação com assistentes de IA
Camada de Implementação de Ferramentas: Implementa a funcionalidade de varredura e gerenciamento YARA
Camada de Abstração de Armazenamento: Fornece opções flexíveis de armazenamento
Integração com o Mecanismo YARA: Utiliza YARA para varredura e gerenciamento de regras

Para diagramas detalhados da arquitetura, consulte a Documentação da Arquitetura.

✨ Recursos

🔄 Arquitetura Modular
- Separação clara entre integração MCP, implementação de ferramentas e armazenamento
- Análise padronizada de parâmetros e tratamento de erros
- Backend de armazenamento flexível com opções locais e S3/MinIO
🤖 Integração MCP
- 19 ferramentas MCP integradas para funcionalidade abrangente
- Otimizado para integração com Claude Desktop
- Análise direta de arquivos dentro de conversas
- Compatível com a especificação mais recente do protocolo MCP
🔍 Varredura YARA
- Varredura de URLs e conteúdo de arquivos
- Informações detalhadas de correspondências com contexto
- Armazenamento e recuperação de resultados de varredura
- Mecanismo de varredura otimizado para desempenho
📝 Gerenciamento de Regras
- Criar, ler, atualizar e excluir regras YARA
- Validação de regras com relatórios detalhados de erros
- Importação de regras do repositório ThreatFlux
- Categorização por origem (personalizada vs. comunidade)
📊 Análise de Arquivos
- Visualização hexadecimal para análise binária
- Extração de strings com parâmetros configuráveis
- Metadados de arquivos e informações de hash
- Upload e armazenamento seguro de arquivos
🔐 Recursos de Segurança
- Autenticação JWT para acesso à API
- Execução em contêiner sem usuário root
- Isolamento seguro de armazenamento
- Controles de acesso configuráveis

🚀 Início Rápido

Usando Imagem Docker

# 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

Instalação a partir do Código-Fonte

# 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

🧩 Integração com Claude Desktop

O YaraFlux é projetado para integração perfeita com o Claude Desktop por meio do Model Context Protocol.

Construa a imagem Docker:

docker build -t yaraflux-mcp-server:latest .

Adicione à configuração do Claude Desktop (~/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"
      ]
    }
  }
}

Reinicie o Claude Desktop para ativar o servidor.

🛠️ Ferramentas MCP Disponíveis

O YaraFlux expõe 19 ferramentas MCP integradas:

Ferramentas de Gerenciamento de Regras

list_yara_rules: Lista regras YARA disponíveis com opções de filtragem
get_yara_rule: Obtém o conteúdo e os metadados de uma regra YARA específica
validate_yara_rule: Valida a sintaxe de regras YARA com relatórios detalhados de erros
add_yara_rule: Cria uma nova regra YARA
update_yara_rule: Atualiza uma regra YARA existente
delete_yara_rule: Exclui uma regra YARA
import_threatflux_rules: Importa regras do repositório GitHub ThreatFlux

Ferramentas de Varredura

scan_url: Varre conteúdo de uma URL com regras YARA especificadas
scan_data: Varre dados fornecidos (codificados em base64) com regras especificadas
get_scan_result: Recupera resultados detalhados de uma varredura anterior

Ferramentas de Gerenciamento de Arquivos

upload_file: Envia um arquivo para análise ou varredura
get_file_info: Obtém metadados sobre um arquivo enviado
list_files: Lista arquivos enviados com paginação e ordenação
delete_file: Exclui um arquivo enviado
extract_strings: Extrai strings ASCII/Unicode de um arquivo
get_hex_view: Obtém a visualização hexadecimal do conteúdo do arquivo
download_file: Baixa um arquivo enviado

Ferramentas de Gerenciamento de Armazenamento

get_storage_info: Obtém estatísticas de uso de armazenamento
clean_storage: Remove arquivos antigos para liberar espaço de armazenamento

📚 Documentação

Documentação abrangente está disponível no diretório docs/:

Diagramas da Arquitetura - Representação visual da arquitetura do sistema
Análise de Código - Estrutura detalhada do código e recomendações
Guia de Instalação - Instruções detalhadas de configuração
Guia de Uso da CLI - Documentação da interface de linha de comando
Referência da API - Endpoints da API REST e uso
Guia de Regras YARA - Criando e gerenciando regras YARA
Integração MCP - Detalhes da integração com o Model Context Protocol
Gerenciamento de Arquivos - Capacidades de manipulação de arquivos
Exemplos - Exemplos de uso no mundo real

🗂️ Estrutura do Projeto

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

🧪 Desenvolvimento

Desenvolvimento Local

# 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

Fluxos de Trabalho CI/CD

Este projeto usa GitHub Actions para integração contínua e implantação:

Testes de CI: Executados em cada push e pull request para as branches main e develop
- Executa testes, formatação, linting e verificação de tipos
- Constrói e testa imagens Docker
- Envia relatórios de cobertura de testes para o Codecov
Incremento Automático de Versão: Incrementa automaticamente a versão em pushes para a branch main
- Atualiza a versão em pyproject.toml, setup.py e Dockerfile
- Cria tag git para a nova versão
Publicar Lançamento: Acionado após o incremento automático de versão bem-sucedido
- Constrói imagens Docker para múltiplos estágios
- Gera notas de lançamento a partir de commits git
- Cria lançamento no GitHub com artefatos
- Publica imagens Docker no Docker Hub

Esses fluxos de trabalho garantem a qualidade do código e automatizam o processo de lançamento.

Verificações de Status

As seguintes verificações de status são executadas em pull requests:

✅ Verificação de Formatação: Garante que o código segue os padrões de formatação Black e isort
✅ Verificação de Lint: Valida a qualidade do código e a conformidade com os padrões de codificação
✅ Execução de Testes: Executa a suíte completa de testes para verificar a funcionalidade
✅ Relatório de Cobertura: Garante cobertura suficiente de testes do código

🌐 Documentação da API

Documentação interativa da API disponível em:

Swagger UI: http://localhost:8000/docs
ReDoc: http://localhost:8000/redoc

Para documentação detalhada da API, consulte a Referência da API.

🤝 Contribuindo

Contribuições são bem-vindas! Sinta-se à vontade para enviar um Pull Request.

Faça um fork do repositório
Crie sua branch de recurso (git checkout -b feature/amazing-feature)
Faça commit das suas alterações (git commit -m 'Add some amazing feature')
Envie para a branch (git push origin feature/amazing-feature)
Abra um Pull Request

📄 Licença

Este projeto é licenciado sob a Licença MIT - consulte o arquivo LICENSE para detalhes.