使用说明
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
- 通过SDKMAN安装:
- Osquery 安装和
osqueryi在您的PATH中可用 - Gradle(或使用附带的Gradle包装)
安装
- 克隆存储库:
git clone https://github.com/yourusername/OsqueryMcpServer.git
cd OsqueryMcpServer
- 构建项目:
./gradlew build # Build server + client, run all tests
./gradlew bootJar # Create executable JAR
cd client-springai && ../gradlew build # Build Spring AI client
- 构建本机映像(可选,推荐):
sdk use java 25.0.2-graalce
./gradlew nativeCompile --no-configuration-cache
# Binary at: build/native/nativeCompile/OsqueryMcpServer
- 运行服务器:
# JVM mode
./gradlew bootRun
# Native mode (instant startup)
./build/native/nativeCompile/OsqueryMcpServer
- 测试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
- 运行测试:
./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许可证。看 许可证 了解详情。