Metadata-Version: 2.4
Name: ssh-forensics-mcp
Version: 0.1.0
Summary: SSH 远程取证 MCP Server：通道原语 + 本机主动探测 + JSONL 证据链
Author: xihan123
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/xihan123/ssh-forensics
Project-URL: Repository, https://github.com/xihan123/ssh-forensics
Project-URL: Issues, https://github.com/xihan123/ssh-forensics/issues
Keywords: ssh,forensics,mcp,incident-response,security
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Information Technology
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Security
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: mcp<2,>=1.2.0
Requires-Dist: asyncssh>=2.17.0

![ssh-forensics-mcp](https://socialify.git.ci/xihan123/ssh-forensics/image?description=1&forks=1&issues=1&language=1&name=1&owner=1&pulls=1&stargazers=1&theme=Auto)

![Python](https://img.shields.io/badge/Python-3.10%2B-brightgreen.svg)
[![Build and publish](https://github.com/xihan123/ssh-forensics/actions/workflows/release.yml/badge.svg)](https://github.com/xihan123/ssh-forensics/actions/workflows/release.yml)
![Version](https://img.shields.io/github/v/release/xihan123/ssh-forensics?label=version)
![PyPI](https://img.shields.io/pypi/v/ssh-forensics-mcp)

# ssh-forensics-mcp

面向已授权目标的 SSH 远程取证 MCP Server，提供「通道 + 探测 + 证据链」原语：

- SSH 连接、只读命令执行、SFTP 小文件读取、证据原件下载和会话管理；
- 本机 TCP 端口扫描（nmap 优先）与 HTTP 指纹抓取；
- 每次调用自动写入按主机隔离的 JSONL 证据链。

面板识别、部署发现、数据库识别和入侵判断等业务逻辑交给上层 Agent 的
`remote-forensics` Skill 完成，本服务不绑定特定 MCP 客户端。完整 SOP、知识库和
报告模板见仓库：<https://github.com/xihan123/ssh-forensics>。

## 目录

- [环境要求](#环境要求)
- [安装与运行](#安装与运行)
- [MCP 客户端配置](#mcp-客户端配置)
- [推荐取证流程](#推荐取证流程)
- [工具](#工具)
- [只读守卫与安全边界](#只读守卫与安全边界)
- [证据目录](#证据目录)
- [本地开发与验证](#本地开发与验证)
- [合规声明](#合规声明)

## 环境要求

- Python 3.10 及以上；
- 已获授权的 Linux 服务器和可用的 SSH 凭据；
- `uv`（推荐）或 Python/pip；
- `nmap` 可选，未安装时自动回退到内置 TCP connect 扫描。

## 安装与运行

### 使用 PyPI 发布包

由 MCP 客户端直接拉起 stdio 服务：

```bash
uvx ssh-forensics-mcp
```

或安装到当前环境后运行：

```bash
python -m pip install ssh-forensics-mcp
ssh-forensics-mcp
```

### 从源码运行

```bash
cd mcp-ssh-forensics
uv run ssh-forensics-mcp
```

也可以先执行 `python -m pip install -e .`，再运行 `ssh-forensics-mcp`。

## MCP 客户端配置

通用 JSON 配置：

```json
{
  "mcpServers": {
    "ssh-forensics": {
      "command": "uvx",
      "args": ["ssh-forensics-mcp"]
    }
  }
}
```

使用已安装命令时，将 `command` 改成 `ssh-forensics-mcp` 并删除 `args` 即可。Codex CLI：

```bash
codex mcp add ssh-forensics -- uvx ssh-forensics-mcp
```

服务使用 MCP stdio 传输，不监听网络端口；需要通过 URL 接入的客户端应使用其本地
stdio 适配器，而不是把该进程直接暴露到公网。

## 推荐取证流程

1. `ssh_connect` 建连。密码和私钥二选一；有可信基线时填写
   `expected_host_key_fingerprint` 做固定校验。
2. `ssh_exec` 分块运行 `ss -tunlp`、`ps auxf`、日志和配置读取等只读命令。
3. `local_port_scan` 从分析机视角确认暴露面，再用 `local_http_probe` 获取 Web 指纹，
   与 SSH 内部视角交叉验证。
4. 用 `ssh_read_file` 读取小型配置，用 `ssh_download` 保存日志等原件。
5. `evidence_summary` 查看统计；报告引用时同时保存 `incident` 与 `seq`。
6. 报告完成后调用 `ssh_close`。进程退出时服务也会自动关闭剩余会话。

示例调用序列（参数仅供已授权目标使用）：

```text
ssh_connect(host="192.0.2.10", username="ir", private_key_path="~/.ssh/ir_ed25519")
ssh_exec(session_id="<session_id>", command="echo '=== NET ==='; ss -tunlp; ps auxf")
local_port_scan(target="192.0.2.10", ports="22,80,443,8080")
local_http_probe(target="192.0.2.10", port=8080)
evidence_summary(last_n=20)
ssh_close(session_id="<session_id>")
```

## 工具

| 工具 | 说明 |
| --- | --- |
| `ssh_connect(host, username, password\|private_key_path, port, expected_host_key_fingerprint)` | 建连，返回 `session_id` 和 host key 指纹 |
| `ssh_exec(session_id, command, timeout_seconds, enforce_readonly, justification)` | 执行命令；默认只读守卫拦截写操作，自动记证据 |
| `ssh_read_file(session_id, path, max_bytes)` | SFTP 读取小文件（默认最多 64 KiB） |
| `ssh_download(session_id, remote_path, local_filename)` | 下载证据原件到主机专属 `files/` 目录，不覆盖同名文件 |
| `ssh_list_sessions()` / `ssh_close(session_id)` | 会话管理 |
| `local_port_scan(target, ports, use_nmap, timeout_seconds)` | nmap 服务识别或纯 Python TCP 扫描 |
| `local_http_probe(target, port, scheme, path, timeout_seconds)` | HTTP 状态码、响应头、title、摘要和 favicon MD5 |
| `evidence_summary(last_n)` | 事件目录、条目统计及最近记录 |

所有工具返回的 `evidence_seq`（以及摘要里的 `incident`）都可用于定位原始记录。

## 只读守卫与安全边界

`ssh_exec` 默认 `enforce_readonly=True`，会拦截 rm/dd/mkfs/reboot、passwd/useradd、
chmod/chattr/kill、iptables 或 systemctl 改动、crontab 写入、重定向写文件、内联脚本、
容器创建/执行、反取证清理等命令，并记录 `blocked_exec` 证据。命令按 `;`、`|`、`&&`
等段落逐段检查，合并写命令与只读命令也不会绕过守卫。

确需写操作时，必须显式设置 `enforce_readonly=False` 并填写 `justification`；调用会以
`readonly_bypass` 留痕。守卫是防误操作的兜底，不是完整安全边界；请在 Skill 层面同样
遵守最小权限和授权范围。

默认 `known_hosts=None` 跳过首次连接的 host key 比对，只记录本次看到的指纹；这不证明
连接对象身份。提供可信的 `expected_host_key_fingerprint` 后，不匹配会拒绝连接并记录
`host_key_mismatch`。

## 证据目录

默认写入当前工作目录的 `evidence/<主机>-<时间戳>/`：

```text
evidence/
└── 192.0.2.10-20260914-120000/
    ├── evidence.jsonl
    └── files/
```

通过 `SSH_FORENSICS_EVIDENCE_DIR` 可指定其他根目录：

```bash
SSH_FORENSICS_EVIDENCE_DIR=/var/lib/ssh-forensics/evidence uvx ssh-forensics-mcp
```

证据可能包含敏感日志、配置和命令输出，请使用权限受控的目录，并确保该目录已加入
`.gitignore`，不要将证据提交到公开仓库。

## 本地开发与验证

```bash
cd mcp-ssh-forensics
python -m pip install -e .
python -m compileall -q src
python tests/selftest.py
python -m pip install --upgrade build
python -m build
```

`tests/selftest.py` 使用 fake SSH 连接和本机临时 HTTP 服务，覆盖守卫、探测、证据链、
MCP 工具清单与生命周期清理，不需要真实目标机。发行包位于 `dist/`，可用
`python -m pip install dist/*.whl` 做安装烟测。

## 合规声明

本工具仅用于对**拥有明确授权**的服务器进行安全取证与资产盘点。对未授权目标使用属
违法行为；请勿将未加鉴权的服务暴露到公网。工具及其产出的报告、`evidence.jsonl`
证据链均为技术参考性质，不构成司法/审计意义上的正式证据。使用者应自行确认授权、
隐私和数据留存要求，并对使用本项目产生的风险和责任负责。项目按
[Apache-2.0](https://github.com/xihan123/ssh-forensics/blob/master/LICENSE) 授权，按“现状”提供。
