# Memory Shell Detector MCP
基于 FastMCP 构建的 Java 内存马检测和清理工具 MCP 服务器，支持本地执行和 SSH 远程执行。
项目地址：https://github.com/RuoJi6/memory-shell-mcp
## 功能
| 功能 | 工具名称 | 对应命令 |
|------|----------|----------|
| 执行命令（本地/SSH） | `execute_command` | - |
| 下载检测工具 | `download_detector_tools` | - |
| 列出Java进程 | `list_java_processes` | `-l` |
| 扫描指定进程 | `scan_process` | `-s <PID>` |
| 查看可疑类代码 | `view_class_code` | `-v <类名> -p <PID>` |
| 移除内存马 | `remove_memory_shell` | `-r <类名> -p <PID>` |
| 导出检测报告 | `export_report` | `--report` |
| 获取系统信息 | `get_system_info_tool` | - |
| 检测网络状态 | `check_network` | - |
## 安全特性
- 移除内存马前会先获取源代码供 AI 分析确认
- 需要 AI 确认后（`ai_confirmed=True`）才会执行移除操作
- 自动处理移除确认提示
## 环境要求
- Python 3.10+
- JDK 1.8+（目标机器）
- uv（Python 包管理器）
---
## 快速开始（uvx 方式）
发布到 PyPI 后，直接使用 uvx 运行，无需安装：
```bash
uvx memory-shell-mcp
```
### MCP 配置（uvx 方式）
> **支持 MCP 的客户端**：本工具可配置到任何支持 Model Context Protocol 的 AI 客户端，包括但不限于：
> - **IDE/编辑器**：[Cursor](https://cursor.com)、[Windsurf](https://codeium.com/windsurf)、[VS Code](https://code.visualstudio.com)（需安装 Copilot 扩展）、[Zed](https://zed.dev)、[Kiro](https://kiro.dev)
> - **AI 助手**：[Claude Desktop](https://claude.ai/download)、[Claude Code](https://docs.anthropic.com/en/docs/claude-code)
> - **开发工具**：[Cline](https://github.com/cline/cline)（VS Code 扩展）、[Continue](https://continue.dev)、[Roo Code](https://roocode.com)
> - **其他**：[5ire](https://5ire.app)、[BeeAI](https://beeai.dev)、[Genkit](https://firebase.google.com/docs/genkit)、[Goose](https://block.github.io/goose)
>
> 以下是常用客户端的配置示例：
#### Kiro
在 `.kiro/settings/mcp.json` 中添加：
```json
{
"mcpServers": {
"memory-shell-detector": {
"command": "uvx",
"args": ["memory-shell-mcp"],
"env": {},
"disabled": false,
"autoApprove": []
}
}
}
```
#### Claude Desktop
在 `claude_desktop_config.json` 中添加：
```json
{
"mcpServers": {
"memory-shell-detector": {
"command": "uvx",
"args": ["memory-shell-mcp"],
"env": {}
}
}
}
```
> **说明**：`env` 中的环境变量均为可选配置。不配置时，工具会下载到系统临时目录，SSH 参数可通过 AI 对话传入。
---
## 开发者模式（本地源码）
### 安装
```bash
git clone https://github.com/RuoJi6/memory-shell-mcp.git
cd memory-shell-mcp
# 创建虚拟环境并安装依赖
uv venv --python python3.12
source .venv/bin/activate # Linux/macOS
# .venv\Scripts\activate # Windows
uv pip install -e .
```
### 运行
```bash
# 激活虚拟环境后
memory-shell-mcp
```
### MCP 配置（开发者模式）
```json
{
"mcpServers": {
"memory-shell-detector": {
"command": "uv",
"args": [
"run",
"--directory",
"/path/to/memory-shell-mcp",
"memory-shell-mcp"
],
"env": {}
}
}
}
```
> **说明**：`env` 中的环境变量均为可选配置。不配置时，工具会下载到系统临时目录，SSH 参数可通过 AI 对话传入。
---
## 环境变量说明（可选）
| 变量 | 说明 |
|------|------|
| `TOOLS_DIR` | 检测工具（JAR 文件）存放目录，不设置则下载到系统临时目录 |
| `SSH_HOST` | SSH 主机地址 |
| `SSH_USERNAME` | SSH 用户名 |
| `SSH_PASSWORD` | SSH 密码 |
| `SSH_KEY_PATH` | SSH 私钥路径（与密码二选一） |
| `SSH_PORT` | SSH 端口（默认 22） |
| `JAVA_HOME` | JDK 路径（可选） |
> - 所有环境变量均为可选，不配置也可正常使用
> - 设置环境变量后，调用工具时无需每次传入对应参数
> - 如果 `TOOLS_DIR` 目录中已存在工具文件，`download_detector_tools` 会跳过下载
> - SSH 参数也可以通过 AI 对话动态传入，优先级高于环境变量
---
## 使用流程
### 完整检测流程
#### 第一步：准备工作
```
1. 调用 download_detector_tools 下载检测工具
2. 调用 list_java_processes 列出所有 Java 进程，找到目标进程 PID
```
#### 第二步：扫描检测
```
3. 调用 scan_process(pid=目标PID) 扫描目标进程
4. 扫描结果会列出所有可疑类，记录完整类名
```
#### 第三步：源码分析（关键步骤）
```
5. 对每个可疑类调用 view_class_code(class_name="类名", pid=PID) 反编译查看源码
6. 分析源码判断是否为内存马
```
**内存马判断标准：**
- ✅ 是否包含命令执行代码（`Runtime.exec`、`ProcessBuilder`）
- ✅ 是否包含反射调用敏感方法
- ✅ 是否有异常的网络连接或文件操作
- ✅ 是否动态注册 Filter/Servlet/Listener
- ✅ 是否有加密/编码的可疑字符串（Base64、AES 等）
- ✅ 是否有 Webshell 特征（参数名为 cmd/command/exec 等）
- ✅ 类名是否异常（随机字符串、与业务无关）
- ✅ 是否有类加载器操作（defineClass、ClassLoader）
#### 第四步：清除内存马
```
7. 确认是内存马后，调用 remove_memory_shell(class_name="类名", pid=PID, ai_confirmed=True)
8. 移除后立即再次调用 scan_process 验证是否清除成功
9. 重要：某些内存马需要多次移除才能彻底清除，如果仍然存在，重复步骤 7-8
```
#### 第五步：生成报告（可选）
```
10. 调用 export_report 导出检测报告存档
```
---
## 示例提示词
直接复制以下提示词发送给 AI 即可开始检测：
### 本地检测
```
帮我检测本机的 Java Web 服务，排查是否存在内存马。
检测要求：
1. 先下载检测工具，然后列出 Java 进程找到目标 PID
2. 扫描该进程，获取所有可疑类列表
3. 对每个可疑类反编译源代码，分析是否为内存马
4. 如果确认是内存马，执行移除操作
5. 移除后再次扫描验证，某些内存马需要多次移除才能彻底清除
6. 最后给我一个检测报告总结
```
### SSH 远程检测
```
帮我检测远程服务器上的 Java 服务是否存在内存马。
服务器信息：
- IP: 192.168.1.100
- 用户名: root
- 密码: your_password
检测要求：
1. 通过 SSH 连接到服务器
2. 下载检测工具到 /tmp 目录
3. 列出所有 Java 进程，扫描可疑进程
4. 反编译分析每个可疑类的源代码
5. 确认是内存马后执行移除，并验证移除结果
6. 生成检测报告
```
---
## 内存马类型说明
| 类型 | 特征 | 移除难度 |
|------|------|----------|
| Filter 型 | 实现 `javax.servlet.Filter`，动态注册到 FilterChain | 中等，可能需要多次移除 |
| Servlet 型 | 继承 `HttpServlet`，动态注册路由 | 中等 |
| Listener 型 | 实现 `ServletRequestListener` 等 | 较易 |
| Spring Controller | 使用 `@RequestMapping` 动态注册 | 中等 |
| Spring Interceptor | 实现 `HandlerInterceptor` | 中等 |
| Agent 型 | 通过 `Instrumentation` 修改字节码 | 困难，可能需要重启 |
| Valve 型 (Tomcat) | 继承 `ValveBase` | 中等 |
---
## 旧版使用流程（简化版）
### 1. 下载检测工具
```
调用 download_detector_tools
```
### 2. 列出 Java 进程
```
调用 list_java_processes()
```
### 3. 扫描可疑进程
```
调用 scan_process(pid=进程ID)
```
### 4. 查看可疑类源代码
```
调用 view_class_code(class_name="类名", pid=进程ID)
```
### 5. 移除内存马
```
# AI 确认后调用
调用 remove_memory_shell(class_name="类名", pid=进程ID, ai_confirmed=True)
```
---
## SSH 远程执行
### 方式1：环境变量预设
在 MCP 配置的 `env` 中设置：
```json
"env": {
"TOOLS_DIR": "/your/tools/directory",
"SSH_HOST": "192.168.1.100",
"SSH_USERNAME": "root",
"SSH_PASSWORD": "password"
}
```
调用时只需设置 `use_ssh=True`：
```
调用 scan_process(pid=12345, use_ssh=True)
```
### 方式2：AI 对话动态传入
直接告诉 AI SSH 连接信息：
```
调用 scan_process(
pid=12345,
use_ssh=True,
ssh_host="192.168.1.100",
ssh_username="root",
ssh_password="password"
)
```
> 对话传入的参数优先级高于环境变量
---
## 工具下载地址
工具会自动从以下地址下载：
- Agent JAR: `https://xget.xi-xu.me/gh/RuoJi6/memory-shell-mcp/releases/download/1/detector-agent-1.0.0-SNAPSHOT.jar`
- CLI JAR: `https://xget.xi-xu.me/gh/RuoJi6/memory-shell-mcp/releases/download/1/memory-shell-detector-cli.jar`
## 支持系统
- Windows / Linux / macOS
## 风险等级说明
| 等级 | 说明 |
|------|------|
| CRITICAL | 确认为内存马，需立即处理 |
| HIGH | 高度可疑，建议人工确认 |
| MEDIUM | 中等风险，可能是正常组件 |
| LOW | 低风险，基本可排除 |
| SAFE | 安全，已在白名单中 |
## 注意事项
1. 扫描其他进程需要足够的系统权限
2. 目标进程和检测工具需使用相同或兼容的 JDK 版本
3. Agent JAR 需要和 CLI JAR 放在同一目录下
4. Agent 型内存马无法通过本工具移除，需要重启应用
5. 移除内存马可能影响应用正常运行，建议先备份
---
## 发布到 PyPI
```bash
# 1. 注册 PyPI 账号并获取 API Token
# https://pypi.org/manage/account/token/
# 2. 构建包
uv build
# 3. 发布到 PyPI
uv publish --token YOUR_PYPI_TOKEN
# 4. 发布后即可通过 uvx 运行
uvx memory-shell-mcp
```
## 参考项目
- [memory-shell-detector](https://github.com/private-xss/memory-shell-detector) - Java 内存马检测工具核心实现
- [Xget](https://github.com/xixu-me/Xget) - GitHub 文件加速下载服务
## License
MIT License
