系统诊断查询工具

一个通过自然语言查询实现系统诊断的工具,支持AI助手集成、Spring AI客户端和Claude Code技能三种使用方式。

  • by kousen
  • Java
  • 本地部署
  • 15 星标
  • 更新于
在 GitHub 查看 kousen/OsqueryMcpServer

使用说明

Osquery MCP服务器、客户端和技能

集成的完整实施 Osquery 使用AI助手,提供三种方法:用于Claude Desktop的MCP服务器、Spring AI客户端和用于直接CLI使用的Claude Code技能。

概述

该项目通过将自然语言翻译成Osquery SQL查询,使人工智能助手能够回答系统诊断问题,如“为什么我的风扇运行得这么热?”或“什么在使用我所有的内存?”。

将osquery与AI结合使用的三种方法:

方法 最佳选择 工作原理
MCP服务器 Claude Desktop Spring Boot服务器通过MCP协议进行通信
Spring AI客户端 程序化访问 使用Spring AI的MCP自动配置的CLI客户端
克劳德代码技能 克劳德代码命令行界面 直接 osqueryi 通过Bash执行,无需服务器

最新动态

堆栈已升级到最新的Spring生态系统,并支持GraalVM原生映像:

组件 上一个 当前
弹簧靴 3.5.0 4.0.3
春季AI 1.0.0 2.0.0
Java 21 25 (GraalVM CE)
杰克逊 2.x(com.fasterxml) 3.x (tools.jackson)
依赖关系管理 io.spring.dependency-management 插件 Gradle platform() BOM。
本机映像 不支持 GraalVM原生二进制文件(约36ms启动)
系统健康状况 顺序(5个查询) 通过虚拟线程并行

密钥升级详细信息

GraalVM本机映像:MCP服务器编译为约62MB的本机二进制文件,该文件在约36ms内启动并响应MCP请求。这对于语音接口用例至关重要——当JavaFX语音客户端启动服务器时,它需要立即响应。

虚拟线程: getSystemHealthSummary() 现在,使用以下命令并行运行所有5个诊断查询(CPU、内存、磁盘、网络、温度) Executors.newVirtualThreadPerTaskExecutor() 随着 CompletableFuture.supplyAsync()这将响应时间从所有查询的总和减少到最慢的单个查询的持续时间。

杰克逊3移民 (仅限客户端):Spring Boot 4为Jackson 3提供了新的Maven坐标(tools.jackson.core 而不是 com.fasterxml.jackson.core),不可变的构建器(JsonMapper.builder().build() 而不是 new ObjectMapper()),以及未经检查的异常(JacksonException 而不是 JsonProcessingException).

Gradle构建更改:Spring Boot 4掉落 io.spring.dependency-management 插件。依赖关系现在使用Gradle原生管理 platform() BOM。Spring AI 2.0.0是Maven Central上的GA,因此不需要里程碑存储库。

特性

MCP服务器

  • 自然语言系统诊断问诸如“我的CPU在用什么?”之类的问题,并得到明智的答案
  • 11专用工具 对于常见的诊断场景:
    • 执行自定义Osquery SQL查询
    • 获取表架构和可用列
    • 查找CPU/内存/磁盘I/O使用率高的进程
    • 分析网络连接
    • 检查系统温度和风扇速度(macOS)
    • 识别可疑流程
    • 获取全面的系统健康状况摘要(并行执行)
    • 访问常见问题的示例查询
  • 智能查询辅助:内置示例和模式发现有助于AI构建更好的查询
  • 基于STDIO的MCP集成:与Claude Desktop和其他MCP兼容的AI工具无缝协作
  • 使用Java 25的Spring Boot 4.0.3:最新的Spring生态系统,支持GraalVM原生映像
  • GraalVM本机映像:瞬时MCP响应的启动时间低于200毫秒(测量值约为36毫秒)

Spring AI MCP客户端

  • Spring AI自动配置:利用Spring AI 2.0的MCP客户端启动器进行零配置设置
  • 交互式CLI:探索性系统诊断的REPL接口
  • 自然语言处理:将人工问题映射到适当的服务器工具
  • 自定义SQL支持:通过MCP服务器执行直接osquery命令
  • 自动工具发现:通过以下方式发现的工具 SyncMcpToolCallbackProvider 注射
  • 内置错误处理:框架管理的超时和流程管理
  • 声明性配置:基于YAML的设置,便于维护
  • 杰克逊3:使用不可变 JsonMapper 构建器模式与现代API
  • 全面测试:包括查询映射逻辑的自动单元测试

克劳德代码技能

  • 零开销:不需要服务器进程-运行 osqueryi 直接通过Bash
  • 自然语言触发器:系统诊断问题自动激活
  • 预定义查询模板:与MCP服务器相同的诊断查询
  • 基线指导:包括用于解释结果的“这正常吗?”上下文
  • 安全说明:解释流程可疑的原因(以及常见的误报)
  • 平台意识:注意macOS与Linux的差异
  • 易于维护:只需标记文件-编辑并重新启动Claude Code

性能和可靠性

  • 本机映像启动:第一个MCP响应大约需要36毫秒(JVM启动需要几秒钟)
  • 并行查询:系统运行状况摘要通过虚拟线程并发运行5个查询
  • 查询超时:防止查询超时30秒,版本检查超时5秒挂起
  • 流程管理:使用ProcessBuilder进行稳健的资源处理和适当的清理
  • 执行时间记录:跟踪查询性能以进行监视和调试
  • 错误处理:从失败的查询中捕获并返回详细的错误消息
  • 资源安全:自动销毁超过超时限制的进程

先决条件

  • Java 25+ (建议使用GraalVM CE 25来支持本机映像)
    • 通过SDKMAN安装: sdk install java 25.0.2-graalce
  • Osquery 安装和 osqueryi 在您的PATH中可用
  • Gradle(或使用附带的Gradle包装)

安装

  1. 克隆存储库:
git clone https://github.com/yourusername/OsqueryMcpServer.git
cd OsqueryMcpServer
  1. 构建项目:
./gradlew build        # Build server + client, run all tests
./gradlew bootJar      # Create executable JAR
cd client-springai && ../gradlew build  # Build Spring AI client
  1. 构建本机映像(可选,推荐):
sdk use java 25.0.2-graalce
./gradlew nativeCompile --no-configuration-cache
# Binary at: build/native/nativeCompile/OsqueryMcpServer
  1. 运行服务器:
# JVM mode
./gradlew bootRun

# Native mode (instant startup)
./build/native/nativeCompile/OsqueryMcpServer
  1. 测试Spring AI MCP客户端:
# 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
  1. 运行测试:
./gradlew :test                              # Server tests
./gradlew :client-springai:test              # Spring AI client tests
./gradlew build                              # All tests

用法

MCP服务器

服务器在STDIO模式下运行,并提供11个用于系统诊断的专用工具:

Spring AI MCP客户端

客户端提供多种与服务器交互的方式:

自然语言查询

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\""

自定义SQL查询

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

交互模式

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

克劳德代码技能

当您在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?

安装

选项1:项目级(包含在本回购中)

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

选项2:个人(跨所有项目工作)

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

运作原理

这项技能引导克劳德奔跑 osqueryi 直接命令:

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

无需服务器-Claude通过Bash执行查询并解释JSON结果。

可用的服务器工具

核心工具

  • executeOsquery(sql):执行任何有效的Osquery SQL查询
  • listOsqueryTables():获取系统上所有可用的Osquery表
  • getTableSchema(tableName):查找任何表的列和类型

诊断工具

  • getHighCpuProcesses():查找消耗CPU最多的进程
  • getHighMemoryProcesses():查找使用最多内存的进程
  • getHighDiskIOProcesses():查找具有高磁盘读/写活动的进程
  • getNetworkConnections():显示带有进程信息的活动网络连接
  • getTemperatureInfo():获取系统温度和风扇速度(macOS)
  • getSuspiciousProcesses():识别具有异常特征的流程

辅助工具

  • getCommonQueries():获取常见诊断场景的示例查询
  • getSystemHealthSummary():全面了解CPU、内存、磁盘、网络和温度(通过虚拟线程并行运行所有查询)

AI交互示例

现在,您可以问自然语言问题,而不是编写复杂的SQL:

“为什么我的电脑运行缓慢?” ->AI使用 getHighCpuProcesses() 和 getHighMemoryProcesses()

“什么连接到互联网?” ->AI使用 getNetworkConnections()

“为什么我的粉丝这么大声?” ->AI使用 getTemperatureInfo() 检查系统温度

“显示所有Chrome进程” ->AI使用 executeOsquery() 使用模式发现

“给我做一次全面的系统健康检查” ->AI使用 getSystemHealthSummary() 用于全面诊断(并行运行5个查询)

“我的系统被破坏了吗?” ->AI使用 getSuspiciousProcesses() 检查是否有异常

配置

应用程序通过以下方式配置 src/main/resources/application.properties:

  • 服务器名称:osquery服务器
  • 版本: 1.0.0
  • 模式:SYNC(同步操作)
  • 运输:STDIO(标准输入/输出)

MCP集成

该服务器使用Spring AI的MCP服务器启动器实现模型上下文协议(MCP)。它可以与支持MCP的AI工具集成,例如:

  • Claude桌面应用程序
  • 其他与MCP兼容的AI助手

MCP配置示例

对于Claude Desktop,请添加到您的配置中:

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

或者使用本地二进制文件进行即时启动(~36ms):

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

安全考虑

警告:此服务器以运行用户的权限执行系统命令。考虑以下安全措施:

  • 以最低权限运行
  • 在生产环境中实施查询过滤或白名单
  • 监控并记录所有已执行的查询
  • 考虑使用只读Osquery查询

发展

项目架构

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)

生成配置

该项目使用Gradle platform() 依赖管理的BOM(Spring Boot 4删除了 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"))
    // ...
}

运行测试

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

塑造本土形象

# 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

备注:The --no-configuration-cache 由于GraalVM构建工具插件0.10.6和Gradle 9的配置缓存序列化之间存在已知的不兼容性,因此需要标记。

内置诊断查询

该服务器包括用于常见诊断场景的预构建查询。使用 getCommonQueries() 查看所有可用示例:

性能分析

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

网络分析

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

系统信息

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

人工智能可以将这些作为模板或直接调用专门的诊断工具。

贡献

欢迎投稿!请随时提交拉取请求。

许可证

MIT许可证。看 许可证 了解详情。

致谢

  • Osquery 通过Facebook
  • 春季AI MCP 用于MCP协议实现
  • Spring Boot框架
  • 用于本机映像编译的GraalVM