Osquery MCP Server

Um servidor MCP para Osquery que permite que assistentes de IA respondam perguntas de diagnóstico do sistema usando linguagem natural.

GitHub

Experimente este MCPPatrocinado

Documentação

Osquery MCP Server, Client & Skill

Uma implementação completa para integrar Osquery com assistentes de IA, oferecendo três abordagens: um servidor MCP para Claude Desktop, um cliente Spring AI e uma skill do Claude Code para uso direto via CLI.

Visão Geral

Este projeto permite que assistentes de IA respondam a perguntas de diagnóstico do sistema, como "Por que meu ventilador está tão quente?" ou "O que está usando toda a minha memória?", traduzindo linguagem natural em consultas SQL do Osquery.

Três maneiras de usar osquery com IA:

Abordagem	Melhor Para	Como Funciona
Servidor MCP	Claude Desktop	Servidor Spring Boot se comunica via protocolo MCP
Cliente Spring AI	Acesso programático	Cliente CLI usando a auto-configuração MCP do Spring AI
Skill do Claude Code	CLI do Claude Code	Execução direta de `osqueryi` via Bash, sem necessidade de servidor

O Que Há de Novo

A stack foi atualizada para o ecossistema Spring mais recente com suporte a imagem nativa GraalVM:

Componente	Anterior	Atual
Spring Boot	3.5.0	4.0.3
Spring AI	1.0.0	2.0.0
Java	21	25 (GraalVM CE)
Jackson	2.x (`com.fasterxml`)	3.x (`tools.jackson`)
Gerenciamento de dependências	plugin `io.spring.dependency-management`	BOMs Gradle `platform()`
Imagem nativa	Não suportado	Binário nativo GraalVM (~36ms de inicialização)
Saúde do sistema	Sequencial (5 consultas)	Paralelo via virtual threads

Detalhes Principais da Atualização

Imagem Nativa GraalVM: O servidor MCP compila para um binário nativo de ~62MB que inicia e responde a solicitações MCP em ~36ms. Isso é crítico para o caso de uso de interface de voz — quando um cliente de voz JavaFX inicia o servidor, ele precisa responder instantaneamente.

Virtual Threads: getSystemHealthSummary() agora executa todas as 5 consultas de diagnóstico (CPU, memória, disco, rede, temperatura) em paralelo usando Executors.newVirtualThreadPerTaskExecutor() com CompletableFuture.supplyAsync(). Isso reduz o tempo de resposta da soma de todas as consultas para a duração da consulta individual mais lenta.

Migração para Jackson 3 (somente cliente): O Spring Boot 4 inclui o Jackson 3 com novas coordenadas Maven (tools.jackson.core em vez de com.fasterxml.jackson.core), builders imutáveis (JsonMapper.builder().build() em vez de new ObjectMapper()) e exceções não verificadas (JacksonException em vez de JsonProcessingException).

Mudanças no Build Gradle: O Spring Boot 4 remove o plugin io.spring.dependency-management. As dependências agora são gerenciadas com BOMs nativos do Gradle platform(). O Spring AI 2.0.0 está GA no Maven Central, portanto nenhum repositório de milestone é necessário.

Recursos

Servidor MCP

Diagnóstico de Sistema em Linguagem Natural: Faça perguntas como "O que está usando minha CPU?" e obtenha respostas inteligentes
11 Ferramentas Especializadas para cenários comuns de diagnóstico:
- Executar consultas SQL personalizadas do Osquery
- Obter esquemas de tabelas e colunas disponíveis
- Encontrar processos com alto uso de CPU/memória/E/S de disco
- Analisar conexões de rede
- Verificar temperatura do sistema e velocidade dos ventiladores (macOS)
- Identificar processos suspeitos
- Obter resumo abrangente da saúde do sistema (execução paralela)
- Acessar consultas de exemplo para problemas comuns
Assistência Inteligente de Consultas: Exemplos integrados e descoberta de esquemas ajudam a IA a construir melhores consultas
Integração MCP baseada em STDIO: Funciona perfeitamente com Claude Desktop e outras ferramentas de IA compatíveis com MCP
Spring Boot 4.0.3 com Java 25: Ecossistema Spring mais recente com suporte a imagem nativa GraalVM
Imagem Nativa GraalVM: Inicialização abaixo de 200ms para respostas MCP instantâneas (~36ms medidos)

Cliente MCP Spring AI

Auto-configuração Spring AI: Aproveita o starter de cliente MCP do Spring AI 2.0 para configuração zero
CLI Interativo: Interface REPL para diagnósticos exploratórios do sistema
Processamento de Linguagem Natural: Mapeia perguntas humanas para as ferramentas apropriadas do servidor
Suporte a SQL Personalizado: Execute comandos osquery diretamente através do servidor MCP
Descoberta Automática de Ferramentas: Ferramentas descobertas via injeção de SyncMcpToolCallbackProvider
Tratamento de Erros Integrado: Timeouts gerenciados pelo framework e gerenciamento de processos
Configuração Declarativa: Configuração baseada em YAML para fácil manutenção
Jackson 3: Usa padrão de builder imutável JsonMapper e APIs modernas
Testes Abrangentes: Inclui testes unitários automatizados para a lógica de mapeamento de consultas

Skill do Claude Code

Zero Overhead: Nenhum processo de servidor necessário — executa osqueryi diretamente via Bash
Gatilhos de Linguagem Natural: Ativa automaticamente para perguntas de diagnóstico do sistema
Modelos de Consulta Predefinidos: As mesmas consultas de diagnóstico do servidor MCP
Orientação de Referência: Inclui contexto de "isso é normal?" para interpretar resultados
Explicações de Segurança: Explica o que torna os processos suspeitos (e falsos positivos comuns)
Consciência de Plataforma: Observa diferenças entre macOS e Linux
Manutenção Fácil: Apenas arquivos markdown — edite e reinicie o Claude Code

Desempenho e Confiabilidade

Inicialização de Imagem Nativa: ~36ms até a primeira resposta MCP (vs vários segundos para inicialização da JVM)
Consultas Paralelas: O resumo de saúde do sistema executa 5 consultas simultaneamente via virtual threads
Timeouts de Consulta: Evita travamentos com timeout de 30 segundos para consultas e 5 segundos para verificações de versão
Gerenciamento de Processos: Usa ProcessBuilder para manipulação robusta de recursos e limpeza adequada
Registro de Tempo de Execução: Rastreia o desempenho das consultas para monitoramento e depuração
Tratamento de Erros: Captura e retorna mensagens de erro detalhadas de consultas com falha
Segurança de Recursos: Destrói automaticamente processos que excedem os limites de timeout

Pré-requisitos

Java 25+ (GraalVM CE 25 recomendado para suporte a imagem nativa)
- Instale via SDKMAN: sdk install java 25.0.2-graalce
Osquery instalado e osqueryi disponível no seu PATH
Gradle (ou use o Gradle wrapper incluído)

Instalação

Clone o repositório:

git clone https://github.com/yourusername/OsqueryMcpServer.git
cd OsqueryMcpServer

Compile o projeto:

./gradlew build        # Build server + client, run all tests
./gradlew bootJar      # Create executable JAR
cd client-springai && ../gradlew build  # Build Spring AI client

Compile a imagem nativa (opcional, recomendado):

sdk use java 25.0.2-graalce
./gradlew nativeCompile --no-configuration-cache
# Binary at: build/native/nativeCompile/OsqueryMcpServer

Execute o servidor:

# JVM mode
./gradlew bootRun

# Native mode (instant startup)
./build/native/nativeCompile/OsqueryMcpServer

Teste o cliente MCP Spring AI:

# Natural language queries
cd client-springai && ../gradlew run --args="\"What's using my CPU?\""

# Interactive mode
../gradlew run --args="--interactive"

# Custom SQL queries
../gradlew run --args="\"SELECT name FROM system_info\""

# Run test suite
./test-client-springai.sh

Execute os testes:

./gradlew :test                              # Server tests
./gradlew :client-springai:test              # Spring AI client tests
./gradlew build                              # All tests

Uso

Servidor MCP

O servidor opera em modo STDIO e fornece onze ferramentas especializadas para diagnóstico do sistema:

Cliente MCP Spring AI

O cliente oferece várias maneiras de interagir com o servidor:

Consultas em Linguagem Natural

cd client-springai
../gradlew run --args="\"What's using my CPU?\""
../gradlew run --args="\"Show network connections\""
../gradlew run --args="\"Why is my fan running?\""
../gradlew run --args="\"Show system health\""
../gradlew run --args="\"Check for suspicious processes\""
../gradlew run --args="\"Show high disk I/O processes\""

Consultas SQL Personalizadas

../gradlew run --args="\"SELECT name, pid, cpu_time FROM processes ORDER BY cpu_time DESC LIMIT 5\""
../gradlew run --args="\"SELECT * FROM system_info\""

Modo Interativo

../gradlew run --args="--interactive"
# Then type queries interactively, 'help' for assistance, 'exit' to quit

Skill do Claude Code

A skill ativa automaticamente quando você faz perguntas de diagnóstico do sistema no Claude Code:

> Why is my computer slow?
> What's using all my memory?
> Show me network connections
> Are there any suspicious processes?
> Why is my fan running?

Instalação

Opção 1: Nível de projeto (incluído neste repositório)

# Already available in .claude/skills/osquery/ when working in this project

Opção 2: Pessoal (funciona em todos os projetos)

cp -r .claude/skills/osquery ~/.claude/skills/
# Restart Claude Code to load the skill

Como Funciona

A skill orienta o Claude a executar comandos osqueryi diretamente:

osqueryi --json "SELECT name, pid, resident_size FROM processes ORDER BY resident_size DESC LIMIT 10"

Nenhum servidor necessário — o Claude executa consultas via Bash e interpreta os resultados JSON.

Ferramentas Disponíveis no Servidor

Ferramentas Principais

executeOsquery(sql): Execute qualquer consulta SQL válida do Osquery
listOsqueryTables(): Obtenha todas as tabelas Osquery disponíveis no seu sistema
getTableSchema(tableName): Descubra colunas e tipos para qualquer tabela

Ferramentas de Diagnóstico

getHighCpuProcesses(): Encontre processos que consomem mais CPU
getHighMemoryProcesses(): Encontre processos que usam mais memória
getHighDiskIOProcesses(): Encontre processos com alta atividade de leitura/gravação em disco
getNetworkConnections(): Mostre conexões de rede ativas com informações do processo
getTemperatureInfo(): Obtenha temperatura do sistema e velocidade dos ventiladores (macOS)
getSuspiciousProcesses(): Identifique processos com características incomuns

Ferramentas Auxiliares

getCommonQueries(): Obtenha consultas de exemplo para cenários comuns de diagnóstico
getSystemHealthSummary(): Obtenha uma visão geral abrangente de CPU, memória, disco, rede e temperatura (executa todas as consultas em paralelo via virtual threads)

Exemplos de Interações com IA

Em vez de escrever SQL complexo, você agora pode fazer perguntas em linguagem natural:

"Por que meu computador está lento?" -> A IA usa getHighCpuProcesses() e getHighMemoryProcesses()

"O que está se conectando à internet?" -> A IA usa getNetworkConnections()

"Por que meu ventilador está tão barulhento?" -> A IA usa getTemperatureInfo() para verificar as temperaturas do sistema

"Mostre-me todos os processos do Chrome" -> A IA usa executeOsquery() com descoberta de esquema

"Faça uma verificação geral da saúde do sistema" -> A IA usa getSystemHealthSummary() para diagnósticos abrangentes (5 consultas executadas em paralelo)

"Meu sistema está comprometido?" -> A IA usa getSuspiciousProcesses() para verificar anomalias

Configuração

O aplicativo é configurado através de src/main/resources/application.properties:

Nome do Servidor: osquery-server
Versão: 1.0.0
Modo: SYNC (operação síncrona)
Transporte: STDIO (entrada/saída padrão)

Integração MCP

Este servidor implementa o Model Context Protocol (MCP) usando o starter de Servidor MCP do Spring AI. Ele pode ser integrado com ferramentas de IA que suportam MCP, como:

Aplicativo Claude Desktop
Outros assistentes de IA compatíveis com MCP

Exemplo de Configuração MCP

Para o Claude Desktop, adicione à sua configuração:

{
  "mcpServers": {
    "osquery": {
      "command": "java",
      "args": ["-jar", "path/to/osquery-mcp-server.jar"]
    }
  }
}

Ou com o binário nativo para inicialização instantânea (~36ms):

{
  "mcpServers": {
    "osquery": {
      "command": "path/to/OsqueryMcpServer"
    }
  }
}

Considerações de Segurança

Aviso: Este servidor executa comandos do sistema com os privilégios do usuário em execução. Considere as seguintes medidas de segurança:

Execute com os privilégios mínimos necessários
Implemente filtragem de consultas ou lista de permissões em produção
Monitore e registre todas as consultas executadas
Considere usar consultas Osquery somente leitura

Desenvolvimento

Arquitetura do Projeto

src/                                    # MCP Server (Spring Boot 4)
├── main/java/com/kousenit/osquerymcpserver/
│   ├── OsqueryMcpServerApplication.java      # Main application
│   └── OsqueryService.java                   # MCP tools (virtual threads)
└── test/java/com/kousenit/osquerymcpserver/
    └── OsqueryServiceTest.java               # Server tests

client-springai/                        # Spring AI 2.0 MCP Client
├── src/main/java/com/kousenit/osqueryclient/springai/
│   └── SpringAiOsqueryClientApplication.java # CLI application (Jackson 3)
├── src/test/java/com/kousenit/osqueryclient/springai/
│   └── QueryMappingTest.java                 # Unit tests
├── application.yml                          # Spring AI configuration
└── test-client-springai.sh                  # Test runner

.claude/skills/osquery/                 # Claude Code Skill
├── SKILL.md                                 # Skill definition & triggers
└── queries.md                               # Query templates & baselines

build.gradle.kts                            # Server build (GraalVM native)

Configuração de Build

O projeto usa Gradle com BOMs platform() para gerenciamento de dependências (o Spring Boot 4 remove o plugin io.spring.dependency-management):

plugins {
    java
    id("org.springframework.boot") version "4.0.3"
    id("org.graalvm.buildtools.native") version "0.10.6"  // Server only
}

dependencies {
    implementation(platform("org.springframework.boot:spring-boot-dependencies:4.0.3"))
    implementation(platform("org.springframework.ai:spring-ai-bom:2.0.0"))
    // ...
}

Executando Testes

./gradlew :test                          # Server tests
./gradlew :client-springai:test          # Spring AI client tests
./gradlew build                          # All tests
./test-client-springai.sh                # Full client test suite

Compilando a Imagem Nativa

# Requires GraalVM CE 25
sdk install java 25.0.2-graalce
sdk use java 25.0.2-graalce

# Build (takes ~25 seconds)
./gradlew nativeCompile --no-configuration-cache

# Test
./build/native/nativeCompile/OsqueryMcpServer

Nota: A flag --no-configuration-cache é necessária devido a uma incompatibilidade conhecida entre o plugin GraalVM buildtools 0.10.6 e a serialização do cache de configuração do Gradle 9.

Consultas de Diagnóstico Integradas

O servidor inclui consultas pré-construídas para cenários comuns de diagnóstico. Use getCommonQueries() para ver todos os exemplos disponíveis:

Análise de Desempenho

-- Top CPU consuming processes
SELECT name, pid, uid, (user_time + system_time) AS cpu_time FROM processes ORDER BY cpu_time DESC LIMIT 10;

-- Memory usage by process
SELECT name, pid, resident_size, total_size FROM processes ORDER BY resident_size DESC LIMIT 10;

Análise de Rede

-- Active network connections
SELECT pid, local_address, local_port, remote_address, remote_port, state
FROM process_open_sockets WHERE state = 'ESTABLISHED'

Informações do Sistema

-- Overall system info
SELECT hostname, cpu_brand, physical_memory, hardware_vendor, hardware_model FROM system_info;

-- Recent file changes
SELECT path, mtime, size FROM file WHERE path LIKE '/Users/%'
AND mtime > (strftime('%s', 'now') - 3600)

A IA pode usá-las como modelos ou chamar as ferramentas de diagnóstico especializadas diretamente.

Contribuindo

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

Licença

Licença MIT. Consulte Licença para detalhes.

Agradecimentos

Osquery pelo Facebook
Spring AI MCP pela implementação do protocolo MCP
Framework Spring Boot
GraalVM pela compilação de imagem nativa