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 客户端配置
• 推荐取证流程
• 工具
• 只读守卫与安全边界
• 证据目录
• 本地开发与验证
• 合规声明

环境要求

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

安装与运行

使用 PyPI 发布包

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

uvx ssh-forensics-mcp

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

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

从源码运行

cd mcp-ssh-forensics
uv run ssh-forensics-mcp

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

MCP 客户端配置

通用 JSON 配置：

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

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

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。进程退出时服务也会自动关闭剩余会话。

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

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

工具

所有工具返回的 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/<主机>-<时间戳>/：

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

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

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

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

本地开发与验证

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 授权，按“现状”提供。