SSH 远程执行命令 / 脚本,把每条输出渲染成终端风格截图(png / jpg / jpeg / webp / bmp,默认 jpeg)+ 清单归档
Run commands or scripts over SSH, render every output as a terminal-style image (png / jpg / jpeg / webp / bmp, jpeg by default), ship a machine-readable manifest.
ssh-shot 把「连上去跑命令」和「截图留证」合成一步。给出目标主机与凭据,它会:
- 通过 SSH 登录(密码 / 私钥 / ssh-agent);
- 逐条执行命令或脚本(申请 PTY,保留远端 ANSI 颜色);
- 把每条输出交给 termshot 渲染成终端风格图片,再按需转成 jpeg / webp / bmp(默认 jpeg);
- 生成
manifest.json,记录命令原文、退出码、耗时、输出字节数与脚本 SHA-256。
适合需要「可复核证据」而不是一段随手复制文本的场景:服务器巡检、安全基线核查、故障排查、应急响应验证、审计取证。
- 四种执行源,可任意混用:
-c命令、--commands-json清单、--script本地脚本、--remote-script远端脚本。 - 批量服务器:
--hosts-file一次对多台主机执行同一批命令,每台只出一张图,按{ip}_{目录名}命名。 - 真实终端观感:PTY +
xterm-256color,ls --color、systemctl status等彩色输出完整保留。 - 图片格式可自定义:默认 jpeg,可切换 png / jpg / webp / bmp;质量可调(默认 90),底色默认取截图自带的深色。
- 溯源信息内嵌在图上:每张图自带彩色提示符行(命令原文)、
[exit N] (耗时);脚本任务额外带本地路径与 SHA-256。 - 终端框自适应铺满:按输出最长行自动定列宽(45–120 列),终端框铺满整图、无阴影、无外部背景块。
- 脚本上传即用即清:本地脚本经 SFTP 上传、
chmod 700、执行完毕后默认删除,远端不留残留。 - 远端脚本可存证:
--remote-script会把脚本内容拉回证据目录并计入 SHA-256,证明「跑的是哪一份」。 - 原始文本另存:每张图都附带同名的
.ansi原文,可随时重新渲染,不必再连一次。 - 失败可见:超时标黄、非零退出标红,既画在图上也写进清单;单条命令失败不会中断整批采集。
| 组件 | 版本 | 说明 |
|---|---|---|
| Python | 3.9+ | 仅用于本机脚本(远端无需 Python) |
| paramiko | 3.0+ | SSH / SFTP 客户端 |
| Pillow | 10+ | PNG → jpeg / webp / bmp 转换、固定画布宽度(出图必需) |
| termshot | 0.4+ | ANSI → PNG 渲染器(Go CLI) |
| 操作系统 | macOS / Linux | Windows 请使用 WSL 或 Git Bash |
git clone https://github.com/rootphantomer/ssh-shot-skill.git && cd ssh-shot-skill
bash scripts/install.shinstall.sh 会创建 .venv 并安装 paramiko 与 Pillow,然后安装 termshot:优先 go install,没有 Go 则提示使用 Homebrew 或下载 Release。
# 1) Python 依赖(任选其一)
uv venv .venv && uv pip install --python .venv/bin/python 'paramiko>=3.0' 'Pillow>=10'
python3 -m venv .venv && ./.venv/bin/python -m pip install 'paramiko>=3.0' 'Pillow>=10'
# 2) termshot(任选其一)
go install github.com/homeport/termshot/cmd/termshot@latest # 产物位于 $(go env GOPATH)/bin/termshot
brew install homeport/tap/termshot脚本会在 PATH、~/go/bin、/usr/local/bin、/opt/homebrew/bin、/usr/bin 中查找 termshot;也可以用 --termshot /path/to/termshot 显式指定。
./.venv/bin/python scripts/ssh_shot.py \
--host 10.0.0.5 -u root -p 'YOUR_PASSWORD' \
-c "uname -a; uptime" -c "ss -lntp"执行结束会打印证据目录,其中包含每一条命令的 .ansi、.jpg(默认 jpeg 格式)与总清单 manifest.json。要换格式加 --image-format png|jpg|jpeg|webp|bmp;加 --merge 可把多条命令输出拼成一张 merged.jpg。
省略
-p时脚本会用getpass交互索要密码,避免明文留在 shell history 里。
# 单条
$PY scripts/ssh_shot.py --host 10.0.0.5 -p 'PASS' -c "uname -a"
# 多条(按顺序,各出一张图)
$PY scripts/ssh_shot.py --host 10.0.0.5 -p 'PASS' \
-c "hostname; uptime" \
-c "df -h" \
-c "ss -lntp"
# 私钥 + 非默认端口 + 窄终端
$PY scripts/ssh_shot.py --host 10.0.0.5 --port 2222 -u ops -i ~/.ssh/id_ed25519 \
-c "systemctl status sshd" --cols 160批量巡检推荐使用 JSON 清单,格式见 scripts/commands.sample.json:
[
{
"id": "row01",
"name": "basic-info",
"command": "hostname; uname -a; id",
"timeout": 30
}
]| 字段 | 必填 | 说明 |
|---|---|---|
id |
否 | 截图文件名前缀,缺省自动编号 rowNN;会做文件名安全化处理 |
name |
否 | 描述性标签,只用于清单与截图标题 |
command |
是 | 实际下发的命令 |
timeout |
否 | 本条命令的超时秒数,覆盖全局 --timeout |
$PY scripts/ssh_shot.py --host 10.0.0.5 -p 'PASS' \
--commands-json scripts/commands.sample.json -o ./evidence对一批主机执行同一批命令时,用 --hosts-file 提供纯文本清单(格式见 scripts/hosts.sample.txt),每行 ip user password,# 开头为注释:
10.0.0.5 root YourPassword1
10.0.0.6 ops YourPassword2
$PY scripts/ssh_shot.py --hosts-file scripts/hosts.sample.txt \
--commands-json scripts/commands.sample.json \
-o ./巡检报告 # 不存在则自动新建批量模式的行为:
- 每台主机按清单里的账号密码登录,执行完全相同的命令;
- 每台强制把多命令输出拼成一张图,图尾一个汇总 exit;
- 输出目录里只有图片,无
.ansi、manifest.json、时间戳子目录等; - 图片命名为
{ip}_{目录名}.jpg,目录名即-o文件夹名(如10.0.0.5_巡检报告.jpg); - 单台失败(连接/认证/采集)不影响其他台,最后汇总成功/失败数。
批量模式用清单里的密码认证,忽略
-p/-i;--host与--hosts-file二选一。
$PY scripts/ssh_shot.py --host 10.0.0.5 -p 'PASS' --script ./baseline.sh流程:SFTP 上传到 --remote-dir(默认 /tmp/ssh_shot_<时间戳>/)→ chmod 700 → 执行 → 截图 → 默认删除远端文件与目录。
脚本原件会同时复制进证据目录(script.row01.baseline.sh),SHA-256 写入清单,并显示在截图溯源行上。
# 保留远端脚本便于复查;指定解释器;换上传目录
$PY scripts/ssh_shot.py --host 10.0.0.5 -p 'PASS' --script ./baseline.sh \
--keep-remote --remote-dir /tmp/audit --shell "bash -e"目标机上已有脚本时,直接指向它即可,不会修改远端任何文件:
$PY scripts/ssh_shot.py --host 10.0.0.5 -p 'PASS' --remote-script /opt/audit/os.sh执行前会先 stat 确认存在(不存在则直接报错,不会留下一条 exit 127 的假证据),随后按首行 shebang 推断解释器,并把脚本内容拉回证据目录存证(--no-fetch-script 可关闭)。
解释器推断顺序:--shell 显式指定 → 扩展名(.sh→bash、.py→python3、.pl→perl…)→ shebang(支持 #!/usr/bin/env python3、#!/bin/bash -e 等)→ 兜底 bash。
连接
| 参数 | 默认值 | 说明 |
|---|---|---|
--host |
必填 | 目标主机 IP / 域名 |
--port |
22 |
SSH 端口 |
-u, --user |
root |
登录用户名 |
-p, --password |
交互输入 | 密码 |
-i, --key |
– | 私钥路径 |
--key-passphrase |
– | 私钥口令(或用 --ask-key-passphrase 交互输入) |
--no-agent |
关 | 不使用 ssh-agent |
--connect-timeout |
15 |
连接超时(秒) |
执行源
| 参数 | 说明 |
|---|---|
-c, --command |
要执行的命令,可重复 |
--commands-json |
命令清单 JSON 文件 |
--script |
本地脚本:上传后执行,可重复 |
--remote-script |
远端已有脚本路径,可重复 |
--shell |
解释器,如 bash、python3、"bash -e" |
--remote-dir |
上传目录,默认 /tmp/ssh_shot_<时间戳> |
--keep-remote |
保留远端上传的脚本与目录 |
--no-fetch-script |
不把远端脚本拉回证据目录 |
--timeout |
单条命令超时(秒),默认 60 |
终端与会话
| 参数 | 默认值 | 说明 |
|---|---|---|
--cols |
200 |
远端 PTY 列宽 |
--rows |
60 |
远端 PTY 行高 |
--term |
xterm-256color |
PTY TERM 类型 |
--no-pty |
关 | 不申请 PTY:无颜色,但不会被分页器卡住 |
--keep-cr |
关 | 保留 \r(默认转换为 \n) |
输出与渲染
| 参数 | 默认值 | 说明 |
|---|---|---|
-o, --output |
./evidence |
证据根目录(批量模式下为图片输出目录,不存在则新建) |
--hosts-file |
– | 主机清单纯文本(每行 ip user password),批量对多台执行同一批命令 |
--termshot |
自动查找 | termshot 可执行文件路径 |
--no-render |
关 | 只保存 .ansi,不出图 |
--width-source |
screen |
宽度基准:screen=本机最大屏幕物理像素(默认),terminal=当前终端列数 |
--merge |
关 | 多条命令按序执行后,把输出拼成一张图(不再逐条出图);图尾只保留一个汇总 exit(最差状态 + 总耗时) |
--render-columns |
0 |
手动指定列数(0=由 --width-source 决定) |
--padding |
– | 图片内边距(像素)(终端框铺满,无外边距/阴影) |
--no-decoration |
关 | 去掉窗口标题栏按钮(阴影默认不画) |
--render-timeout |
90 |
单张渲染超时(秒) |
--image-format |
jpeg |
截图格式:png / jpg / jpeg / webp / bmp(jpg 与 jpeg 都存为 .jpg) |
--image-quality |
90 |
有损格式质量 1–100,对 jpg / jpeg / webp 生效 |
--image-background |
auto |
底色:auto / black / white / #RRGGBB;auto 取截图自带深色,不会是白底。JPEG/BMP 补透明区、PNG/WebP 固定宽度时补透明 |
evidence/
└── 10.0.0.5_20261118-110852/
├── manifest.json # 主机、时间、渲染参数、脚本信息、每条命令的结果
├── row01.ansi # 捕获到的原始 ANSI 文本(可重新渲染)
├── row01.jpg # 截图(默认 jpeg;按 --image-format 变化)
├── row02.ansi
├── row02.jpg
# 使用 --merge 时改为:
# merged.ansi # 所有命令输出按序拼接, 图尾仅一个汇总 exit
# merged.jpg # 唯一截图
批量模式 (--hosts-file) 输出目录只有图片:
./巡检报告/
├── 10.0.0.5_巡检报告.jpg
├── 10.0.0.6_巡检报告.jpg
└── ...
└── script.row02.baseline.sh # 脚本存证副本(SHA-256 记在清单里)
manifest.json 结构:
{
"tool": "ssh_shot.py",
"created_at": "2026-11-18T11:08:52",
"target": { "host": "10.0.0.5", "port": 22, "user": "root" },
"render": { "termshot": "/usr/local/bin/termshot", "pty": true, "cols": 200, "rows": 60,
"format": "jpeg", "quality": 90, "background": "auto", "clip_canvas": true, "shadow": false,
"width_source": {"source": "screen", "screen_px": 3072, "columns": 103}, "merge": false },
"scripts": { "remote_dir": "/tmp/ssh_shot_20261118-110852", "kept": false, "uploaded": ["/tmp/ssh_shot_20261118-110852/baseline.sh"] },
"summary": { "total": 2, "ok": 2, "failed": 0 },
"results": [
{
"id": "row01",
"command": "uname -a",
"exit_status": 0,
"duration": 0.04,
"output_bytes": 531,
"ansi_file": "row01.ansi",
"image_file": "row01.jpg",
"sha256": "",
"error": "",
"timed_out": false
}
]
}重新渲染任意一页(无需再次连接目标机):
termshot --raw-read evidence/10.0.0.5_20261118-110852/row01.ansi \
--filename /tmp/row01.png
# termshot 只出 PNG;若要 jpeg,需先铺底色再转(底色见 manifest.render.background)
./.venv/bin/python -c "from PIL import Image; im=Image.open('/tmp/row01.png').convert('RGBA'); \
bg=Image.new('RGB', im.size, (21,21,21)); bg.paste(im, mask=im.getchannel('A')); \
bg.save('row01.jpg', quality=90)"退出码
| 码 | 含义 |
|---|---|
0 |
全部采集成功 |
1 |
有命令失败或超时(截图仍会生成,图上以红/黄字标注),或批量模式有主机失败 |
2 |
参数或环境问题,例如 termshot 缺失、脚本不存在、缺 Pillow 或图片格式参数非法 |
┌────────────┐ ① exec + PTY (xterm-256color) ┌────────────┐
本地 ─────────│ paramiko │──────────────────────────────────▶│ 目标主机 │
│ SSHClient │◀──────────────────────────────────│ shell │
└─────┬──────┘ ② stdout/stderr 原始 ANSI └────────────┘
│
│ ③ 加上溯源头(命令原文 / sha256 / exit / 耗时)
▼
row01.ansi ──④ termshot --raw-read──▶ 临时 PNG
│ │
│ └─⑤ Pillow 转换 ──▶ row01.jpg
└──⑥ 汇总 ──▶ manifest.json
不依赖本地伪终端,也不在远端启动任何常驻进程:命令输出经 SSH 通道原样取回,落盘为 ANSI 文本,再由 termshot 离屏渲染。因此渲染阶段可离线重做,也不会因为本地终端尺寸影响远端输出。
本仓库同时是一个符合 Agent Skills 规范 的技能包:
ssh-shot/
├── SKILL.md # 技能定义:名称、触发条件、工作流、规则、自检清单
├── references/ # 渐进式披露的细节,只在需要时加载
│ ├── cli.md # 完整参数、退出码、manifest 字段
│ ├── troubleshooting.md # 常见故障与处理
│ └── playbooks.md # 只读巡检命令组(基础/账号/网络/服务/日志/补丁)
├── scripts/ # 主程序、安装脚本、自测服务端、技能自校验
└── README.md
SKILL.md 的 name 字段为 ssh-shot,按规范目录名需与之一致,因此克隆时指定目录名:
git clone https://github.com/rootphantomer/ssh-shot-skill.git ssh-shot
ln -s "$PWD/ssh-shot" ~/.pi/agent/skills/ssh-shot # pi
ln -s "$PWD/ssh-shot" ~/.claude/skills/ssh-shot # Claude Code校验技能是否符合规范:
python3 scripts/validate_skill.py .
# [ok] ssh-shot: SKILL.md 符合 Agent Skills 规范随后即可用自然语言触发(Agent 会自行组装命令):
「登录 10.0.0.5,跑一遍账号与端口基线检查,把结果截图归档到 evidence/」
- 默认只读:目标是采集证据,不是改配置。请对任何写操作(重启服务、改权限、清日志)预先取得授权。
- 凭据不落盘:密码只存在于进程内存;不写日志、不写清单,建议用
--key或交互输入而非-p(避免 shell history)。 - 远端零残留:上传的脚本执行完毕即删除(
--keep-remote可保留),不安装任何软件、不写系统目录。 - 敏感输出:如命令结果含口令、密钥、令牌,请事先裁剪命令,或对
.ansi使用termshot --edit后再出图。 - 主机密钥:默认接受未知主机密钥(
AutoAddPolicy),便于首次连接内网设备;对高安全要求环境,请预先维护known_hosts并自行收紧策略。 - 主机清单含明文密码:
hosts.sample.txt类文件请勿提交版本库,按需要放入.gitignore。
- 交互式程序(
less、vim、top全屏模式)在截图中会失真,请改用--no-pty或top -b -n1、| cat等非交互写法。 - termshot 只能输出 PNG;jpeg / bmp 没有 alpha,透明区域按
--image-background铺底(默认取截图自带深色,不是白底),png / webp 保留透明。 - 列宽默认按本机最大屏幕物理像素换算(约 3072px→103 列,运行时校准),也可用
--width-source terminal跟随当前终端列数;拿不到时用内容自适应(45–120 列)。终端框铺满画布、无阴影、无额外背景;超长行由 termshot 折行(内容不丢)。 - 需要严格分栏时用
--render-columns手动指定列数。 - 远端登录 banner、
TMOUT提示会出现在输出顶部(属真实情况,不做过滤)。 manifest.json中的 SHA-256 只覆盖脚本内容,不覆盖输出内容;如需完整性证明,请对证据目录整体做签名。
仓库内置一个最小 SSH 服务端(密码认证 + exec + SFTP 子系统,仅监听 127.0.0.1),
无需真实目标机即可端到端验证采集链路:
./.venv/bin/python scripts/fake_sshd.py --port 2222 --password 123456 &
./.venv/bin/python scripts/ssh_shot.py --host 127.0.0.1 --port 2222 -p 123456 \
-c "uname -a; id" \
--script ./baseline.sh \
--remote-script /opt/audit/os.sh \
-o /tmp/evidencefake_sshd.py 会把 SFTP 落到本机文件系统,仅供本地测试,请勿在共享网络中运行。
欢迎 Issue 与 Pull Request:
-
Fork 本仓库并从
main拉出特性分支; -
保持提交信息清晰(推荐 Conventional Commits);
-
涉及行为的改动请补充自测步骤或更新
SKILL.md/README.md; -
提交前跑一遍自检:
python3 -m py_compile scripts/ssh_shot.py scripts/validate_skill.py python3 scripts/validate_skill.py .
MIT © 2026 rootphantomer
