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执行，无需服务器 |
特性
MCP服务器
- 自然语言系统诊断问诸如“我的CPU在用什么？”之类的问题，并得到明智的答案
- 9专用工具 对于常见的诊断场景：
- 执行自定义Osquery SQL查询 - 获取表架构和可用列 - 查找CPU/内存使用率高的进程 - 分析网络连接 - 检查系统温度和风扇速度（macOS） - 获取全面的系统运行状况摘要 - 访问常见问题的示例查询
- 智能查询辅助：内置示例和模式发现有助于AI构建更好的查询
- 基于STDIO的MCP集成：与Claude Desktop和其他MCP兼容的AI工具无缝协作
- 使用Java 21的Spring Boot 3.5：使用Java 17+功能的现代、高效和可维护的代码库
Spring AI MCP客户端
- Spring AI自动配置：利用Spring AI的MCP客户端启动器进行零配置设置
- 交互式CLI：探索性系统诊断的REPL接口
- 自然语言处理：将人工问题映射到适当的服务器工具
- 自定义SQL支持：通过MCP服务器执行直接osquery命令
- 自动工具发现：通过以下方式发现的工具
SyncMcpToolCallbackProvider注射 - 内置错误处理：框架管理的超时和流程管理
- 声明性配置：基于YAML的设置，便于维护
- 综合测试：包括查询映射逻辑的自动单元测试
克劳德代码技能
- 零开销：不需要服务器进程-运行
osqueryi直接通过Bash - 自然语言触发器：系统诊断问题自动激活
- 预定义查询模板：与MCP服务器相同的诊断查询
- 基线指导：包括用于解释结果的“这正常吗？”上下文
- 安全说明：解释流程可疑的原因（以及常见的误报）
- 平台意识：注意macOS与Linux的差异
- 易于维护：只需标记文件-编辑并重新启动Claude Code
性能和可靠性
- 查询超时：防止查询超时30秒，版本检查超时5秒挂起
- 流程管理：使用ProcessBuilder进行稳健的资源处理和适当的清理
- 执行时间记录：跟踪查询性能以进行监视和调试
- 错误处理：从失败的查询中捕获并返回详细的错误消息
- 资源安全：自动销毁超过超时限制的进程
先决条件
- Java 21或更高版本
- Osquery 安装和
osqueryi在您的PATH中可用 - Gradle（或使用附带的Gradle包装）
安装
- 克隆存储库：
git clone https://github.com/yourusername/OsqueryMcpServer.git
cd OsqueryMcpServer- 构建项目：
./gradlew build # Build server
./gradlew bootJar # Create executable JAR
cd client-springai && ../gradlew build # Build Spring AI client- 运行服务器：
./gradlew bootRun- 测试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 --tests OsqueryServiceTest # Server tests
cd client-springai && ../gradlew test # Spring AI client tests用法
MCP服务器
服务器在STDIO模式下运行，并提供九种用于系统诊断的专用工具：
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\""自定义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()：查找使用最多内存的进程getNetworkConnections()：显示带有进程信息的活动网络连接getTemperatureInfo()：获取系统温度和风扇速度（macOS）
辅助工具
getCommonQueries()：获取常见诊断场景的示例查询getSystemHealthSummary()：全面了解CPU、内存、磁盘、网络和温度
AI交互示例
现在，您可以问自然语言问题，而不是编写复杂的SQL：
“为什么我的电脑运行缓慢？” → AI使用 getHighCpuProcesses() 和 getHighMemoryProcesses()
“什么连接到互联网？” → AI使用 getNetworkConnections()
“为什么我的粉丝这么大声？” → AI使用 getTemperatureInfo() 检查系统温度
“显示所有Chrome进程” → AI使用 executeOsquery() 使用模式发现
“给我做一次全面的系统健康检查” → AI使用 getSystemHealthSummary() 用于全面诊断
配置
应用程序通过以下方式配置 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"]
}
}
}安全考虑
⚠️ 警告：此服务器以运行用户的权限执行系统命令。考虑以下安全措施：
- 以最低权限运行
- 在生产环境中实施查询过滤或白名单
- 监控并记录所有已执行的查询
- 考虑使用只读Osquery查询
发展
项目结构
├── src/
│ ├── main/
│ │ ├── java/
│ │ │ └── com/kousenit/osquerymcpserver/
│ │ │ ├── OsqueryMcpServerApplication.java
│ │ │ └── OsqueryService.java
│ │ └── resources/
│ │ └── application.properties
│ └── test/
│ └── java/
└── build.gradle.kts项目架构
├── src/ # MCP Server (Spring Boot)
│ ├── main/java/com/kousenit/osquerymcpserver/
│ │ ├── OsqueryMcpServerApplication.java # Main application
│ │ └── OsqueryService.java # MCP tools
│ └── test/java/com/kousenit/osquerymcpserver/
│ └── OsqueryServiceTest.java # Server tests
├── client-springai/ # Spring AI MCP Client
│ ├── src/main/java/com/kousenit/osqueryclient/springai/
│ │ └── SpringAiOsqueryClientApplication.java # CLI application
│ ├── 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 config运行测试
./gradlew test # Server tests
cd client-springai && ../gradlew test # Spring AI client tests
./test-client-springai.sh # Full client test suite内置诊断查询
该服务器包括用于常见诊断场景的预构建查询。使用 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许可证。看 许可证 了解详情。