@pyrokine/mcp-ssh 2.4.3 → 3.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +257 -49
- package/README_zh.md +251 -68
- package/dist/command-risk.d.ts +2 -1
- package/dist/command-risk.js +238 -87
- package/dist/directory-verification.d.ts +7 -3
- package/dist/directory-verification.js +302 -208
- package/dist/file-mode.d.ts +6 -0
- package/dist/file-mode.js +71 -0
- package/dist/file-ops.d.ts +38 -7
- package/dist/file-ops.js +822 -293
- package/dist/forward-manager.d.ts +2 -0
- package/dist/forward-manager.js +19 -10
- package/dist/openssh.d.ts +51 -0
- package/dist/openssh.js +528 -0
- package/dist/operation-manager.d.ts +4 -4
- package/dist/operation-manager.js +28 -3
- package/dist/pty-manager.d.ts +5 -13
- package/dist/pty-manager.js +47 -15
- package/dist/remote-platform.d.ts +13 -0
- package/dist/remote-platform.js +132 -0
- package/dist/security.js +12 -2
- package/dist/session-manager.d.ts +31 -15
- package/dist/session-manager.js +483 -120
- package/dist/ssh-config.d.ts +3 -0
- package/dist/ssh-config.js +48 -20
- package/dist/tools/connection.js +132 -3
- package/dist/tools/exec.d.ts +1 -0
- package/dist/tools/exec.js +108 -31
- package/dist/tools/file.js +406 -129
- package/dist/tools/operation.js +1 -1
- package/dist/tools/pty.js +5 -3
- package/dist/tools/utils.js +2 -2
- package/dist/types.d.ts +63 -2
- package/dist/utf8.d.ts +1 -0
- package/dist/utf8.js +10 -0
- package/dist/windows-acl.d.ts +4 -0
- package/dist/windows-acl.js +109 -0
- package/package.json +4 -3
package/README_zh.md
CHANGED
|
@@ -11,6 +11,61 @@
|
|
|
11
11
|
 
|
|
12
12
|

|
|
13
13
|
|
|
14
|
+
## 迁移到 3.0
|
|
15
|
+
|
|
16
|
+
`maxOutputSize`
|
|
17
|
+
现在按 UTF-8 字节分别限制 exec 的 stdout/stderr 返回正文,原来按 JavaScript 字符串长度计量;非 ASCII 输出需要重新计算预算,并检查
|
|
18
|
+
`stdoutTruncated` / `stderrTruncated`;`maxOutputSize=3` 可返回一个汉字,不能返回三个,文本只返回完整字符
|
|
19
|
+
|
|
20
|
+
PTY 的 `bufferSize` 参数与列表结果中的 `bufferSize`,以及 read/list 中的 `unreadRawBytes` 和 `rawBufferLimit`
|
|
21
|
+
均按原始字节计量;raw 读取使用 `clear=true` 时,响应中的计数和 `rawBufferTruncated`
|
|
22
|
+
描述清理前的状态,下次读取才反映清理后的缓冲区;精确读取 ANSI 或二进制输出用 `dataBase64`,`data` 是 UTF-8 文本预览
|
|
23
|
+
|
|
24
|
+
文件读取支持 `encoding`(`auto`、`utf8`、`utf16le`、`utf16be`、`gbk`)和无损 `binary=true`;偏移按字节计量,分页使用
|
|
25
|
+
`next_offset`,`auto`
|
|
26
|
+
在文件起始处判断编码,后续分页也使用该判断,非零偏移的 U+FEFF 保留为正文;预算不足以容纳下一个完整字符时返回错误,EOF 处编码无效也会失败;binary 读取按实际字节前移;`lineRange`
|
|
27
|
+
的行号和末行换行状态只描述已返回的前缀
|
|
28
|
+
|
|
29
|
+
连接 Windows 主机须设置 `remotePlatform="windows"`,本机为 Windows 不会改变远端默认值;按主机设置 `commandShell` 和
|
|
30
|
+
`remotePathStyle`,使用 Windows rsync 时显式设置 `rsyncProfile`;下文 Windows 功能和示例继续适用
|
|
31
|
+
|
|
32
|
+
## 复用已有 OpenSSH 主连接
|
|
33
|
+
|
|
34
|
+
默认 `backend="ssh2"` 保留密码与密钥认证、跳板、SFTP、PTY 和转发,设置 `backend="openssh"` 复用终端已经建立的 master:
|
|
35
|
+
|
|
36
|
+
```text
|
|
37
|
+
ssh_connect(backend="openssh", configHost="myserver", alias="shared")
|
|
38
|
+
ssh_exec(alias="shared", command="pwd", cwd="/tmp", env={TASK: "inspect"})
|
|
39
|
+
ssh_sync(alias="shared", localPath="/local/data", remotePath="/remote/data", direction="upload", verify={sha256: true})
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
`ssh -G` 解析有效的 host、user、port 和 `ControlPath`,也可通过 `controlPath` 显式指定 socket,`configPath`
|
|
43
|
+
保留原有路径与文件大小校验
|
|
44
|
+
|
|
45
|
+
OpenSSH 按原生规则处理 `Host`、`Match`、`Include` 和 `ProxyJump`,其中包含用户配置的 `Match exec`
|
|
46
|
+
命令;实际执行阶段使用已经解析的目标和 socket,不重新读取这份配置
|
|
47
|
+
|
|
48
|
+
该后端只复用已有连接,master 不存在、被替换或失效时明确报错;实际命令和 rsync 通道在复用失败后通过失败代理终止,不新建 SSH 连接、重新认证或转用 ssh2/SFTP
|
|
49
|
+
|
|
50
|
+
通过 configHost 或 controlPath 选择已有 master,password、key、agent 和 `jumpHost` 等新认证参数在连接前拒绝
|
|
51
|
+
|
|
52
|
+
连接结果包含 `backend`、`masterReused`、`masterPid`、`identityStatus="master_trusted"`
|
|
53
|
+
和实际观测的登录信息,沿用用户所选 master 的信任;工具检查 socket 所有权、alias 配置冲突和登录用户不符,不把 `ssh -G` 或
|
|
54
|
+
`ssh -O check` 描述成独立的远端主机身份认证
|
|
55
|
+
|
|
56
|
+
支持本机和远端均为 POSIX 的命令、tracked operation、文件元数据与 rsync 同步;同步要求本机和远端具备 rsync,远端具备 GNU
|
|
57
|
+
`find`、`stat`、`head` 和 `realpath`,缺少能力时具体报错
|
|
58
|
+
|
|
59
|
+
有界目录 manifest 和流式 SHA-256 校验均使用同一 master,不要求先建立 ssh2 会话或额外安装远端 Python;独立 SFTP 工具、临时脚本上传、PTY、转发和 Windows 组合返回
|
|
60
|
+
`unsupported_backend`
|
|
61
|
+
|
|
62
|
+
每条命令使用独立 shell,`runAs`、`cwd` 和 `env` 显式指定,原终端的 `su` 或环境变量变更不作为新通道状态
|
|
63
|
+
|
|
64
|
+
取消单项只针对已经验证的目标进程;断开 alias 关闭该 alias 的自有通道;MCP 退出关闭自身通道和子进程,用户 master 与终端连接保持打开
|
|
65
|
+
|
|
66
|
+
远端退出状态无法确认时,受影响 operation 保持 `unknown`;`ssh_reconnect`
|
|
67
|
+
重新绑定配置所指的已有 master,不创建新的 master
|
|
68
|
+
|
|
14
69
|
## 功能特性
|
|
15
70
|
|
|
16
71
|
- **多种认证方式**:密码、SSH 密钥
|
|
@@ -29,7 +84,7 @@
|
|
|
29
84
|
- 发送按键和命令
|
|
30
85
|
- 窗口大小调整
|
|
31
86
|
- **文件操作**:上传、下载、读取、写入、目录列表(通过 SFTP)
|
|
32
|
-
-
|
|
87
|
+
- **智能同步**:文件与目录同步,默认 ssh2 在 rsync 不可用时使用 SFTP,OpenSSH 后端保持 rsync
|
|
33
88
|
- **环境配置**:LANG、LC_ALL、自定义环境变量
|
|
34
89
|
- **跳板机支持**:通过堡垒机连接
|
|
35
90
|
|
|
@@ -47,7 +102,7 @@
|
|
|
47
102
|
|
|
48
103
|
## 安装
|
|
49
104
|
|
|
50
|
-
需要 Node.js 20.19
|
|
105
|
+
需要 Node.js 20.19 或更新版本
|
|
51
106
|
|
|
52
107
|
### npm(推荐)
|
|
53
108
|
|
|
@@ -105,12 +160,15 @@ claude mcp add ssh -- node /path/to/mcp-ssh/dist/index.js
|
|
|
105
160
|
| `ssh_reconnect` | 重新连接断开的会话 |
|
|
106
161
|
| `ssh_config_list` | 列出 ~/.ssh/config 中的 Host |
|
|
107
162
|
|
|
108
|
-
`ssh_list_sessions()`
|
|
109
|
-
|
|
163
|
+
`ssh_list_sessions()` 默认返回 `backend`、`alias`、规范化 `identity`、`runAs`、`connected` 和
|
|
164
|
+
`lastUsedAt`,OpenSSH 条目另含 `masterReused` 与 `identityStatus`;使用 `detail=true` 获取连接详情,或通过
|
|
165
|
+
`fields=[...]` 选择字段,任何模式都不返回 `keyPath`
|
|
166
|
+
|
|
167
|
+
ssh2 连接启用 TCP_NODELAY,减少交互命令和小文件 SFTP 请求之间的等待,直连、跳板和替代连接使用相同行为,无需新增选项
|
|
110
168
|
|
|
111
|
-
`ssh_reconnect` 会在发布替代连接前,使绑定旧 client 的 operation、PTY、forward
|
|
169
|
+
`ssh_reconnect` 会在发布替代连接前,使绑定旧 client 的 operation、PTY、forward 和传输能力缓存失效
|
|
112
170
|
|
|
113
|
-
自动重连 timer 绑定发起调度的 session 和 client,不会断开同一 alias
|
|
171
|
+
自动重连 timer 绑定发起调度的 session 和 client,不会断开同一 alias 下后来发布的新会话
|
|
114
172
|
|
|
115
173
|
旧 client 延迟到达的 `close` 不会让过期资源继续挂在同一 alias 下;通过 jump host 建立目标连接时,如果取消发生在
|
|
116
174
|
`forwardOut` pending 阶段,延迟 callback 返回的 channel 会先销毁再结束连接请求
|
|
@@ -127,6 +185,9 @@ claude mcp add ssh -- node /path/to/mcp-ssh/dist/index.js
|
|
|
127
185
|
| `ssh_quick_exec` | 一次性执行:连接、执行、断开 |
|
|
128
186
|
| `ssh_exec_script` | 上传并执行远端临时脚本 |
|
|
129
187
|
|
|
188
|
+
远端为 Windows 时,`ssh_exec_script` 给 PowerShell 脚本写入 UTF-8 BOM,避免 Windows
|
|
189
|
+
PowerShell 将 Unicode 脚本误读为系统编码;CMD 脚本先切换到代码页 65001 再执行 UTF-8 内容,切换失败则终止;POSIX 脚本内容保持不变
|
|
190
|
+
|
|
130
191
|
### 可跟踪任务
|
|
131
192
|
|
|
132
193
|
| 工具 | 描述 |
|
|
@@ -134,7 +195,7 @@ claude mcp add ssh -- node /path/to/mcp-ssh/dist/index.js
|
|
|
134
195
|
| `ssh_operation_start` | 启动可跟踪的长时间远端命令 |
|
|
135
196
|
| `ssh_operation_status` | 读取状态、PID、退出码和输出计数 |
|
|
136
197
|
| `ssh_operation_read` | 按字节偏移读取有上限的 stdout 和 stderr |
|
|
137
|
-
| `ssh_operation_cancel` |
|
|
198
|
+
| `ssh_operation_cancel` | 校验进程身份后取消任务 |
|
|
138
199
|
| `ssh_operation_list` | 列出未过期任务,可按 alias 过滤 |
|
|
139
200
|
|
|
140
201
|
### 文件操作
|
|
@@ -170,6 +231,53 @@ claude mcp add ssh -- node /path/to/mcp-ssh/dist/index.js
|
|
|
170
231
|
| `ssh_forward_close` | 关闭端口转发 |
|
|
171
232
|
| `ssh_forward_list` | 列出所有端口转发 |
|
|
172
233
|
|
|
234
|
+
## Windows 与跨平台 SSH
|
|
235
|
+
|
|
236
|
+
连接 Windows 主机时设置 `remotePlatform="windows"`;默认值始终是 `posix`,与客户端操作系统无关;Windows 默认使用
|
|
237
|
+
`commandShell="powershell"` 和 `remotePathStyle="win32"`;远端 SFTP 若使用 `/C:/...`,设置
|
|
238
|
+
`remotePathStyle="sftp-posix"`;还可选择 `commandShell="cmd"`,`cwd` 和 `env`
|
|
239
|
+
与完整命令放在同一个 shell 命令组中,cmd 注入值含无法安全处理的展开字符时会拒绝;`ssh_quick_exec` 同样支持
|
|
240
|
+
`remotePlatform`、`commandShell` 和 `agent`;Windows 的 `runAs`、`ssh_exec_as_user` 和 `ssh_exec_sudo` 在发送命令前返回
|
|
241
|
+
`unsupported_remote_platform`
|
|
242
|
+
|
|
243
|
+
```text
|
|
244
|
+
ssh_connect(host="example.com", user="tester", agent="\\\\.\\pipe\\openssh-ssh-agent", remotePlatform="windows", commandShell="powershell", remotePathStyle="win32", rsyncProfile="native-win32")
|
|
245
|
+
ssh_exec(alias="tester@example.com:22", command="Get-Location", cwd="C:\\Test Data", env={REGION:"test"})
|
|
246
|
+
ssh_read_file(alias="tester@example.com:22", remotePath="C:\\Test Data\\report.txt", lineRange="1-20", encoding="utf16le")
|
|
247
|
+
```
|
|
248
|
+
|
|
249
|
+
`ssh_connect(agent="...")` 会将 agent socket 或 Windows OpenSSH named pipe 传给 ssh2;Windows 还支持 ssh2 的
|
|
250
|
+
`agent="pageant"`;未显式设置 agent 和私钥时,SSH config 的 `IdentityAgent` 可提供路径;`IdentityAgent none` 或
|
|
251
|
+
`agent="none"`
|
|
252
|
+
明确禁用 agent 和环境 socket 回退,即使配置私钥也保留禁用状态,ProxyJump 主机同样适用;密码和密钥认证仍可使用;显式参数或模板中的
|
|
253
|
+
`agent` 优先于 SSH config;重连保留该选择,外部 OpenSSH/rsync 在 `none`
|
|
254
|
+
下也禁用环境 agent;连接结果返回远端平台、shell、路径格式,以及 Windows 私钥的
|
|
255
|
+
`keyAclStatus`;已有私钥只校验权限,不自动修改;`key_acl_insecure`、`key_acl_unverified`
|
|
256
|
+
均拒绝读取;Windows 会话文件和临时下载文件在写入正文前设置并验证私有 DACL;Windows 脚本和 atomic 上传的临时文件先由 SFTP 独占创建空文件,DACL 验证后才写入正文,清理也使用 SFTP
|
|
257
|
+
|
|
258
|
+
Windows tracked operation 返回 PID 与创建时间;取消时检查进程命令行中的随机 marker 和创建时间,匹配后才执行
|
|
259
|
+
`taskkill /T /F`;`cancellationStatus` 分别返回 `requested`、`unknown` 或 `unsupported`,关闭 SSH
|
|
260
|
+
channel 不代表取消成功;DACL 和进程行为仍需原生 Windows 环境验收
|
|
261
|
+
|
|
262
|
+
`ssh_read_file.lineRange` 只通过 SFTP 扫描,支持 CRLF、UTF-8、UTF-16LE/BE 和 GBK;`encoding="auto"`
|
|
263
|
+
在文件起始处识别 BOM;`binary=true` 返回无损 base64,`content` 和 `content_base64`
|
|
264
|
+
均含编码结果;偏移仍指向远端文件字节;GBK 的随机字节偏移与 tail 无法证明字符边界,需使用 `lineRange` 或
|
|
265
|
+
`binary=true`;非零偏移读取 UTF-16 时须显式指定编码;`ssh_exec.maxOutputSize`
|
|
266
|
+
分别限制 stdout/stderr 正文的 UTF-8 字节数,截断由 `stdoutTruncated`、`stderrTruncated` 单独提示;PTY raw 的
|
|
267
|
+
`dataBase64` 保存原始字节,`data` 是文本预览
|
|
268
|
+
|
|
269
|
+
目录校验通过 SFTP 有界遍历与流式哈希;Windows 上不接受 POSIX `verify.owner`、`verify.mode`;`verify.aclSddl`
|
|
270
|
+
可单独比较 Windows 远端根目录的 DACL SDDL;覆盖已有目标时,`ssh_upload(atomic=true)` 在传输前检查 SFTP
|
|
271
|
+
`posix-rename@openssh.com` 扩展,无法确认支持时不覆盖旧文件;`ssh_sync` 支持
|
|
272
|
+
`rsyncProfile`(`posix`、`native-win32`、`msys2`、`cygwin`)和远端
|
|
273
|
+
`rsyncExecutable`;本机或远端为 Windows 时须显式设置 profile 才探测 rsync;预检失败时改用 SFTP 并返回
|
|
274
|
+
`selectedTransport` 与 `decisionReason`;rsync 传输开始后失败时远端状态标为未知,不自动重新传输
|
|
275
|
+
|
|
276
|
+
Windows 目录上传会在两种传输开始前,按 `exclude` 和 `followSymlinks` 筛选后的源名称检查候选碰撞;名称比较使用 Windows
|
|
277
|
+
ordinal 大小写规则,并查询已存在目标父目录的大小写敏感标志;确认碰撞返回
|
|
278
|
+
`windows_filename_collision`,父目录不存在、shell 不可用、查询超时或响应不完整则返回
|
|
279
|
+
`case_semantics_unverified`,此时没有上传或创建目录,dry-run 也不写入;已存在且启用大小写敏感的目录允许保留仅大小写不同的名称,不从祖先目录推断新目录的规则;没有候选时不增加 PowerShell 或 exec 要求,普通 SFTP-only 上传继续可用,POSIX 上传保留其名称语义
|
|
280
|
+
|
|
173
281
|
## 使用示例
|
|
174
282
|
|
|
175
283
|
### 使用 SSH Config(推荐)
|
|
@@ -219,7 +327,7 @@ ssh_connect(configHost="myserver", configPath="/custom/path/config")
|
|
|
219
327
|
4. ssh_exec_parallel(aliases=["server1", "server2", "server3"], command="uptime")
|
|
220
328
|
```
|
|
221
329
|
|
|
222
|
-
每台主机的结果包含与 `ssh_exec` 相同的元数据,包括 `failureKind`、`effectiveUser`、`cwd
|
|
330
|
+
每台主机的结果包含与 `ssh_exec` 相同的元数据,包括 `failureKind`、`effectiveUser`、`cwd`、截断字段和诊断建议
|
|
223
331
|
`ssh_exec_parallel` 单次最多 32 个 alias,默认最多并发 4 台主机,可用 `maxConcurrency` 调整(最大 8),并支持
|
|
224
332
|
`maxOutputSize` 限制每台主机的输出
|
|
225
333
|
|
|
@@ -234,7 +342,7 @@ ssh_disconnect(alias="myserver")
|
|
|
234
342
|
### 连接模板和 runAs
|
|
235
343
|
|
|
236
344
|
模板可以通过 `SSH_MCP_TEMPLATES` 或 `~/.mcp-ssh/templates.json`
|
|
237
|
-
|
|
345
|
+
提供,工具显式参数优先于模板值;选中的模板会在连接前校验,SSH 端口必须是 1 到 65535 的整数;模板无效时,错误只返回模板名和字段路径,不返回认证值
|
|
238
346
|
|
|
239
347
|
```json
|
|
240
348
|
{
|
|
@@ -295,17 +403,23 @@ ssh_connect(
|
|
|
295
403
|
)及其他 shell(`.profile`),如不需要可设置 `loadProfile=false`
|
|
296
404
|
|
|
297
405
|
`ssh_exec`、`ssh_exec_as_user` 和 `ssh_exec_sudo` 使用相同的身份优先级:`useLoginUser=true` 使用登录用户,否则本次
|
|
298
|
-
`runAs` 覆盖连接级 `runAs`,再使用连接级 `runAs
|
|
406
|
+
`runAs` 覆盖连接级 `runAs`,再使用连接级 `runAs`
|
|
299
407
|
|
|
300
408
|
`ssh_exec` 和 `ssh_exec_as_user`
|
|
301
409
|
返回执行元数据:`loginUser`、`effectiveUser`、`identity`、`cwd`、`resolvedCwd`、`shell`、
|
|
302
410
|
`profileLoaded`、`envInjectedKeys`、`failureKind`、`stdoutBytes`、`stderrBytes` 和截断提示,大输出会返回 `stdoutHead`、
|
|
303
|
-
`stdoutTail`、`stderrHead`、`stderrTail` 和 `recommendedReadCommand
|
|
411
|
+
`stdoutTail`、`stderrHead`、`stderrTail` 和 `recommendedReadCommand`
|
|
304
412
|
|
|
305
|
-
timeout 错误也包含超时前已经产生的 head/tail
|
|
413
|
+
timeout 错误也包含超时前已经产生的 head/tail 输出;stdout 和 stderr 使用增量解码,UTF-8 字符即使跨越多个 SSH data
|
|
414
|
+
chunk,也会完整返回
|
|
306
415
|
|
|
307
|
-
|
|
308
|
-
|
|
416
|
+
`commandRisk`
|
|
417
|
+
按所选 shell 报告破坏性、提权、凭据参数、进程控制及资源使用风险,只读搜索中的敏感词和普通 Python/Node 命令不会仅凭词语触发风险提示
|
|
418
|
+
|
|
419
|
+
`commandRisk`
|
|
420
|
+
仅提供诊断,不改变命令执行或执行结果 POSIX 分类将 here-doc 正文视为输入,支持引用及部分引用 delimiter、反斜杠引用、`<<-`
|
|
421
|
+
和多个 here-doc 在大小写精确匹配的 delimiter 后恢复命令检查;未引用正文与双引号参数内的有效命令替换仍会检查 EOF 的后台
|
|
422
|
+
`&` 会报告;`&&`、重定向、转义 `&` 和引用输入不会误报为后台操作
|
|
309
423
|
|
|
310
424
|
### 可跟踪的长时间命令
|
|
311
425
|
|
|
@@ -332,6 +446,11 @@ listener 会在 SSH exec callback 返回前安装,极短命令即使立即输
|
|
|
332
446
|
`expiresAt`;SSH 会话在 tracked command 运行期间断开后状态变为 `unknown`,不会声称远端进程已经停止,`ssh_exec`
|
|
333
447
|
保持原有同步 timeout 行为
|
|
334
448
|
|
|
449
|
+
POSIX tracked 命令使用可用的 `setsid -w` 等待实际命令,包括 `setsid` 派生子进程的情况;非零退出为
|
|
450
|
+
`failed`,零退出仍可含 stderr 输出命令在 `sh` 下执行,`pipefail` 等 Bash 选项须显式使用 `bash -lc`;没有 `setsid`
|
|
451
|
+
时,`processGroup=false`,取消只针对 PID POSIX 取消先校验 marker,再使用 `sh`
|
|
452
|
+
与 Bash 支持的信号参数发送 TERM,终止期间产生的系统诊断保留在 stderr
|
|
453
|
+
|
|
335
454
|
### 交互式命令(PTY 模式)
|
|
336
455
|
|
|
337
456
|
用于需要终端的命令:
|
|
@@ -362,7 +481,8 @@ ssh_exec_script(alias="server", script=<script-above>, timeout=30000)
|
|
|
362
481
|
ssh_read_file(alias="server", remotePath="/tmp/mcp-log-errors.txt", maxBytes=65536)
|
|
363
482
|
```
|
|
364
483
|
|
|
365
|
-
日志查询由通用命令和文件工具组合完成,不再提供独立的日志专用 MCP
|
|
484
|
+
日志查询由通用命令和文件工具组合完成,不再提供独立的日志专用 MCP 工具;`ssh_exec_script.timeout`
|
|
485
|
+
同时用于临时脚本上传、权限准备和执行阶段;SFTP 上传停滞时按请求的 timeout 结束,不再使用默认 SFTP 预算
|
|
366
486
|
|
|
367
487
|
### 设置环境变量
|
|
368
488
|
|
|
@@ -377,7 +497,7 @@ ssh_connect(
|
|
|
377
497
|
|
|
378
498
|
### 快速一次性执行
|
|
379
499
|
|
|
380
|
-
|
|
500
|
+
无需管理连接,适用于单次命令;`ssh_quick_exec` 为每次调用创建唯一临时 alias,`readyTimeout` 只限制连接阶段,`timeout`
|
|
381
501
|
只限制远端命令执行阶段:
|
|
382
502
|
|
|
383
503
|
```
|
|
@@ -428,27 +548,65 @@ ssh_read_file(alias="server", remotePath="/var/log/app.log", lineRange="120-180"
|
|
|
428
548
|
`verifySize`、`verifyMd5`、`verifyMode`、`verifyOwner`、`verifyMtime`
|
|
429
549
|
会追加显式传输校验,父目录和目标探测、递归建目录、文件哈希、rename、临时文件清理都使用 SFTP,普通上传不依赖 GNU
|
|
430
550
|
`stat`、`md5sum`、`sha256sum`、`mkdir`、`mv` 或
|
|
431
|
-
`rm`,可用于禁用 exec 的 SFTP-only 服务和 BSD
|
|
551
|
+
`rm`,可用于禁用 exec 的 SFTP-only 服务和 BSD 系统,目录 manifest 校验也通过 SFTP 读取远端目录树
|
|
432
552
|
|
|
433
|
-
`ssh_download`
|
|
434
|
-
报告的大小一致后再 rename
|
|
435
|
-
|
|
553
|
+
`ssh_download` 先以 `0600` mode 写入目标同目录的临时文件,SFTP 流关闭且传输字节数与 SFTP `stat`
|
|
554
|
+
报告的大小一致后再 rename 到本地目标;新文件保持 `0600`;替换普通文件时保留其 `rwx`
|
|
555
|
+
位,但不复制 setuid、setgid 或 sticky 位;目标是 symlink、目录或其他非普通对象时,在远端读取开始前拒绝;下载失败、提前截断或取消时会删除临时文件,已有本地目标保持原内容;SFTP 目录列表在构造子路径前会拒绝空名称、`.`、`..`、NUL 和路径分隔符
|
|
436
556
|
|
|
437
557
|
命令执行结果在远端命令非零退出且没有 stdout/stderr 时返回 `emptyOutputFailure=true`,同时给出 effective
|
|
438
558
|
user、cwd 和可用的后续读取建议,`ssh_read_file` 默认读取 1 MiB,`maxBytes` 超过 16 MiB 时会在远端传输前拒绝,返回
|
|
439
559
|
`total_size`、
|
|
440
560
|
`read_offset`、`requested_offset`、`read_bytes`、`read_end`、`next_offset`、`remaining_bytes`、`sample_kind` 和
|
|
441
|
-
`truncated
|
|
442
|
-
`next_offset
|
|
561
|
+
`truncated`,调用方可以区分完整读取、头部样本、尾部样本、字节范围和行范围;文本读取不会截断 UTF-8 字符,后续分段应使用
|
|
562
|
+
`next_offset`;行范围读取不执行远端 shell 工具
|
|
443
563
|
|
|
444
564
|
`ssh_upload`、`ssh_download`、`ssh_read_file`、`ssh_write_file`、`ssh_list_dir`、`ssh_file_info` 和 `ssh_mkdir`
|
|
445
|
-
支持单个 SFTP 操作的 `timeout`,默认 10 分钟,最大 1
|
|
565
|
+
支持单个 SFTP 操作的 `timeout`,默认 10 分钟,最大 1 小时;超时返回 `operationStatus="unknown"` 和
|
|
446
566
|
`retryable=true`,重试前应检查受影响的远端或本地路径
|
|
447
567
|
|
|
568
|
+
`ssh_list_dir` 和 `ssh_file_info` 返回按 `07777` 掩码提取的数值 `mode`,`permissions` 用作展示,其中 setuid/setgid 使用
|
|
569
|
+
`s`/`S`,sticky 使用 `t`/`T`;`verifyMode` 支持 `4755` 等四位八进制值和 `-rwsr-xr-x`
|
|
570
|
+
等权限文本;校验直接比较数值 mode,不从展示文本反向推导
|
|
571
|
+
|
|
572
|
+
### 目录筛选与分页
|
|
573
|
+
|
|
574
|
+
`ssh_list_dir` 未传下列六个参数时,继续返回完整的 `{success, path, count, files}`,条目按目录优先、名称排序,
|
|
575
|
+
`showHidden=false` 排除名称以点开头的条目;传入任一筛选或分页参数后启用有界响应,默认每页最多 100 条、64 KiB
|
|
576
|
+
|
|
577
|
+
| 参数 | 类型 | 合同 |
|
|
578
|
+
| ---------------- | ------------------------ | --------------------------------------------------------------------------- |
|
|
579
|
+
| `namePattern` | string | 名称区分大小写,复用同步 exclude 的 `*` 和 `?` 通配规则,其他字符按字面匹配 |
|
|
580
|
+
| `modifiedAfter` | 带时区的 ISO 8601 string | 修改时间下界,包含,例如 `2026-01-01T00:00:00Z` |
|
|
581
|
+
| `modifiedBefore` | 带时区的 ISO 8601 string | 修改时间上界,不包含,须大于或等于 `modifiedAfter` |
|
|
582
|
+
| `offset` | 非负整数 | 筛选并排序后的条目位置,默认 `0` |
|
|
583
|
+
| `limit` | 正整数 | 单页最多返回条数,有界模式默认 `100` |
|
|
584
|
+
| `maxBytes` | 正整数 | 返回 JSON 文本的 UTF-8 字节预算,包含元数据和格式空白,有界模式默认 `65536` |
|
|
585
|
+
|
|
586
|
+
名称、时间和隐藏文件条件取交集,时间区间为 `[modifiedAfter, modifiedBefore)`,起止相同时返回空结果;有界响应中, `count`
|
|
587
|
+
表示本页条数,`total_count` 表示全部匹配条数,并返回 `offset`、`has_more` 和 `next_offset`,保持筛选条件不变,使用
|
|
588
|
+
`next_offset` 续查,直到 `has_more=false`;偏移达到或超过末尾时返回空页,保留该偏移
|
|
589
|
+
|
|
590
|
+
```text
|
|
591
|
+
ssh_list_dir(
|
|
592
|
+
alias="server", remotePath="/var/log/app", namePattern="*.log",
|
|
593
|
+
modifiedAfter="2026-01-01T00:00:00Z", modifiedBefore="2026-01-02T00:00:00Z",
|
|
594
|
+
offset=0, limit=100, maxBytes=65536
|
|
595
|
+
)
|
|
596
|
+
```
|
|
597
|
+
|
|
598
|
+
字节预算约束成功响应的 JSON 文本,不包含 MCP 协议外层;分页元数据或下一完整条目无法放入预算时,工具返回
|
|
599
|
+
`LIST_DIR_MAX_BYTES_TOO_SMALL`、`requiredBytes`,`offset` 和 `next_offset` 保持不变,提高 `maxBytes`
|
|
600
|
+
后从该位置重试,错误诊断可超过请求预算;条目始终完整返回,不为满足预算而跳过条目
|
|
601
|
+
|
|
602
|
+
每次调用都完成 SFTP `readdir`
|
|
603
|
+
后再筛选和分页,分页只限制响应,不提供远端增量枚举或冻结快照,调用之间目录变化会改变偏移对应的条目;内部目录读取、递归下载、同步和目录校验保持现有枚举合同;默认 ssh2/SFTP 后端不变,OpenSSH
|
|
604
|
+
master 模式仍拒绝独立 SFTP 目录读取
|
|
605
|
+
|
|
448
606
|
### 使用 rsync 或 SFTP 同步目录
|
|
449
607
|
|
|
450
|
-
|
|
451
|
-
host
|
|
608
|
+
默认 ssh2 后端在直连且存在已校验 key path 或可用 SSH agent 时选择 rsync,password、inline key、jump
|
|
609
|
+
host 和其他无法安全交给独立 OpenSSH 进程的路由直接使用 SFTP OpenSSH master 后端始终使用所选主连接,要求 rsync 可用:
|
|
452
610
|
|
|
453
611
|
```
|
|
454
612
|
// 同步本地目录到远程(上传)
|
|
@@ -483,6 +641,9 @@ ssh_sync(..., dryRun=true)
|
|
|
483
641
|
// 上传单文件后校验远端 owner/mode
|
|
484
642
|
ssh_sync(..., direction="upload", verifyOwner="appuser", verifyMode="0644")
|
|
485
643
|
|
|
644
|
+
// 上传或下载单文件后校验,目标也可为目录
|
|
645
|
+
ssh_sync(..., verify={sha256: true, owner: true, mode: true, maxFileBytes: 268435456})
|
|
646
|
+
|
|
486
647
|
// 使用有界 manifest 校验目录
|
|
487
648
|
ssh_sync(
|
|
488
649
|
...,
|
|
@@ -496,8 +657,14 @@ ssh_sync(..., delete=true, verify={deletions: true})
|
|
|
496
657
|
目录源路径在 rsync 和 SFTP 模式下都表示“把源目录内容同步到目标根目录”,目录源使用 `recursive=false`
|
|
497
658
|
会被明确拒绝,相对排除模式按源目录下的相对路径匹配,不含 `/` 的模式匹配每一级 basename
|
|
498
659
|
|
|
499
|
-
|
|
500
|
-
`verify.
|
|
660
|
+
普通文件可在 upload 和 download 中使用 `verify.sha256`、`verify.owner`、`verify.mode` 与 Windows
|
|
661
|
+
`verify.aclSddl`,校验目标为实际传输的文件,结果使用 `kind="single_file"`,返回文件摘要
|
|
662
|
+
`verify.count`、`verify.deletions` 和 `verify.staleFiles`
|
|
663
|
+
要求目录源,单文件传输前会明确拒绝;已知源文件超过请求的哈希字节上限时,也在传输前拒绝
|
|
664
|
+
|
|
665
|
+
目录校验会生成有界的本地和远端 manifest,可比较条目数、SHA-256 root
|
|
666
|
+
manifest、owner、包括 setuid、setgid、sticky 在内的四位八进制 mode、旧文件和删除结果;`verify.deletions=true`
|
|
667
|
+
必须同时设置 `delete=true`,工具会在传输前记录目标目录,只检查这些删除候选是否消失,`staleFiles`
|
|
501
668
|
则独立检查目标端全部额外条目,响应只返回摘要和最多 20 个 mismatch 样本,不返回完整 manifest,默认上限为 10000 个条目、单文件 256
|
|
502
669
|
MiB、总哈希字节 1 GiB,可通过 `verify.maxEntries`、`verify.maxFileBytes` 和 `verify.maxTotalBytes`
|
|
503
670
|
提高到最多 50000 个条目、单文件 4 GiB、总哈希字节 16 GiB,遇到被跳过的 symlink 或不支持的文件系统条目时,校验会明确返回
|
|
@@ -506,15 +673,24 @@ MiB、总哈希字节 1 GiB,可通过 `verify.maxEntries`、`verify.maxFileByt
|
|
|
506
673
|
请求校验后,mismatch、skipped 或校验错误都会令顶层 `success=false`,`transferSuccess` 仍单独表示传输是否完成,
|
|
507
674
|
`verificationStatus`、`verificationSuccess` 和 `failedChecks`
|
|
508
675
|
描述校验结果,SFTP 单文件同步还会返回本地和远端的 size、mode 或 permissions、mtime、owner/group,以及通过 SFTP 流读取计算的 SHA-256 对比,upload 单文件使用
|
|
509
|
-
`verifyOwner` 和 `verifyMode
|
|
510
|
-
|
|
511
|
-
|
|
512
|
-
|
|
513
|
-
|
|
514
|
-
|
|
515
|
-
|
|
676
|
+
`verifyOwner` 和 `verifyMode`,文件和目录逐项校验均可使用 `verify.owner` 和 `verify.mode`
|
|
677
|
+
校验不会自动执行 chown/chmod,SFTP 新目录使用目标端默认权限,新下载文件使用
|
|
678
|
+
`0600`,覆盖既有本地普通文件保留其 rwx 内容和 owner 匹配不代表 mode 匹配,请求 mode 校验时,已完成的传输仍会因权限不同而返回校验失败
|
|
679
|
+
|
|
680
|
+
ssh2 session 在直连且存在已校验 key path 或可用 SSH agent 时选择 rsync,password、inline key 和 jump
|
|
681
|
+
host 会使用 SFTP,因为独立 OpenSSH 进程无法安全继承对应路由或认证材料 OpenSSH master
|
|
682
|
+
session 不经过这项凭证选择,也不回退到 SFTP,`preflightTimeout`、`connectTimeout` 和 `operationTimeout`
|
|
683
|
+
分别限制能力预检、rsync SSH 建连和完整传输,默认值为 10 秒、30 秒和 10 分钟,不具备 rsync 条件的 session 会返回
|
|
684
|
+
`rsyncProbe.status="skipped"` 和路由判定原因,不再省略 probe,rsync 模式设置
|
|
685
|
+
`StrictHostKeyChecking=accept-new`,SFTP 不支持 `delete=true`
|
|
516
686
|
,此类请求会明确失败,不会报告已经删除,如需严格的主机密钥验证与管理,请使用 SFTP 模式
|
|
517
687
|
|
|
688
|
+
符号链接被跳过时,校验会说明目录不完整,download 可排除这些链接后重新同步和校验,`followSymlinks`
|
|
689
|
+
只控制 upload 目录传输失败会保留已知成功文件数、字节数和失败计数;部分文件完成后发生超时,远端状态仍可为 `unknown`
|
|
690
|
+
|
|
691
|
+
`ssh_upload(timeout=...)` 将该期限应用于每次元数据、摘要、传输、校验、rename 和清理操作,清理失败单独报告 tracked
|
|
692
|
+
operation 终态输出以残缺 UTF-8 字符结束时明确返回编码错误;运行中的未完成字符仍可等待后续字节
|
|
693
|
+
|
|
518
694
|
### 持久化 PTY 会话(top、tmux 等)
|
|
519
695
|
|
|
520
696
|
用于持续刷新或需要持续交互的命令:
|
|
@@ -551,11 +727,15 @@ ssh_pty_read(ptyId="pty_1_xxx")
|
|
|
551
727
|
ssh_pty_write(ptyId="pty_1_xxx", data="\x02d")
|
|
552
728
|
```
|
|
553
729
|
|
|
554
|
-
`ssh_pty_read` 和 `ssh_pty_list` 返回 `lastInputAt`、`lastOutputAt`、`lastReadAt
|
|
555
|
-
`foregroundProcess
|
|
730
|
+
`ssh_pty_read` 和 `ssh_pty_list` 返回 `lastInputAt`、`lastOutputAt`、`lastReadAt`、
|
|
731
|
+
`unreadRawBytes`、`rawBufferLimit`、`rawBufferTruncated`、`foregroundProcess`,列表项还返回
|
|
732
|
+
`bufferSize`,这些 size 字段都按字节计数,screen 输出使用增量解码;raw 的 `dataBase64`
|
|
733
|
+
无损保存原始字节,包括不完整的 UTF-8 序列,`data` 是文本预览;`rawBufferTruncated=true`
|
|
734
|
+
表示从上次 clear 起已有更早的 raw 输出因字节上限被丢弃;raw 读取默认
|
|
735
|
+
`clear=true`,响应返回清理前的字节数和截断标志,随后重置 raw 缓冲区和标志;screen 读取不清理 raw 状态;有限命令自然结束后仍可读取最终 screen,返回
|
|
556
736
|
`active=false`,直到显式 close 或 closed session 保留期结束,默认 5 分钟,可通过 `SSH_MCP_PTY_CLOSED_RETENTION_MS`
|
|
557
|
-
|
|
558
|
-
|
|
737
|
+
调整;`ssh_pty_write` 返回 `accepted=true` 表示本地 stream 已接收输入, `backpressured=true`
|
|
738
|
+
只表示缓冲区达到高水位,不代表输入丢失;`ssh_pty_close` 返回 `closed`、`not_found`、`failed` 或
|
|
559
739
|
`unknown`,可重试的失败会保留 PTY 状态
|
|
560
740
|
|
|
561
741
|
常用控制序列:
|
|
@@ -592,17 +772,18 @@ ssh_forward_close(forwardId="fwd_1_xxx", mode="force", timeoutMs=5000)
|
|
|
592
772
|
```
|
|
593
773
|
|
|
594
774
|
关闭成功表示本地 `server.close` 或远端 `unforwardIn` callback 已完成,结果包含 `listenerReleased`、`remoteUnforwarded`、
|
|
595
|
-
`activeConnections`、`closeMode` 和 `retryable
|
|
596
|
-
`acceptingConnections`,`closing`
|
|
775
|
+
`activeConnections`、`closeMode` 和 `retryable`;`ssh_forward_list` 返回 `lifecycle` 和
|
|
776
|
+
`acceptingConnections`,`closing` 状态仍可重试,但不再接收流量;超时或 callback 失败时 forward 仍保留在
|
|
597
777
|
`ssh_forward_list`,可以使用同一 `forwardId` 重试,本地转发关闭成功后端口可立即重新 bind,`remotePort=0`
|
|
598
778
|
会返回实际分配端口,后续连接路由和 `unforwardIn` 都使用该端口
|
|
599
779
|
|
|
600
780
|
forward 在 `listen` 或 `forwardIn` 完成前就进入生命周期管理,disconnect 会取消 pending
|
|
601
|
-
creation
|
|
781
|
+
creation;延迟返回的本地 listener 会被关闭,延迟分配的远端 listener 会被移除;close 开始后立即拒绝新的本地或远端连接
|
|
602
782
|
`forwardOut`、close 和 unforward 的延迟 callback 修改状态前会检查同一生命周期记录,已关闭的 forward 不会重新出现在
|
|
603
783
|
`ssh_forward_list`;每条本地转发连接同时跟踪本地 socket 和 SSH `forwardOut`
|
|
604
|
-
channel,任一端关闭或失败都会销毁另一端,force close 只在两端都销毁且 `activeConnections`
|
|
605
|
-
|
|
784
|
+
channel,任一端关闭或失败都会销毁另一端,force close 只在两端都销毁且 `activeConnections` 归零后返回;remote force
|
|
785
|
+
close 在 `unforwardIn`
|
|
786
|
+
后遵循相同的连接排空规则,同一连接两端的 close/error 事件只递减一次计数;每个 alias 最多允许 32 个 pending `forwardOut`
|
|
606
787
|
请求,close 会等待全部 callback;如果 SSH 服务端始终不回应 channel-open,请求会超时并保留可重试的 forward,同时拒绝同 alias 新建 local
|
|
607
788
|
forward,避免 ssh2 pending channel 继续累积,此时断开 alias 才能释放始终不返回的底层请求
|
|
608
789
|
|
|
@@ -610,21 +791,23 @@ forward,避免 ssh2 pending channel 继续累积,此时断开 alias 才能
|
|
|
610
791
|
|
|
611
792
|
### 连接选项
|
|
612
793
|
|
|
613
|
-
| 选项 | 类型 | 默认值
|
|
614
|
-
| ----------------------- | ------ |
|
|
615
|
-
| `
|
|
616
|
-
| `
|
|
617
|
-
| `
|
|
618
|
-
| `
|
|
619
|
-
| `
|
|
620
|
-
| `
|
|
621
|
-
| `
|
|
622
|
-
| `
|
|
623
|
-
| `
|
|
624
|
-
| `
|
|
625
|
-
| `
|
|
626
|
-
| `
|
|
627
|
-
| `
|
|
794
|
+
| 选项 | 类型 | 默认值 | 描述 |
|
|
795
|
+
| ----------------------- | ------ | ----------- | --------------------------------------------- |
|
|
796
|
+
| `backend` | string | `ssh2` | `ssh2` 或仅复用已有 master 的 `openssh` |
|
|
797
|
+
| `controlPath` | string | `ssh -G` 值 | 已有 OpenSSH control socket |
|
|
798
|
+
| `host` | string | _必需_ | 服务器地址 |
|
|
799
|
+
| `user` | string | _必需_ | 用户名 |
|
|
800
|
+
| `password` | string | - | 密码认证 |
|
|
801
|
+
| `keyPath` | string | - | SSH 私钥路径 |
|
|
802
|
+
| `port` | number | 22 | SSH 端口 |
|
|
803
|
+
| `alias` | string | 自动生成 | 连接别名,用于后续引用 |
|
|
804
|
+
| `template` | string | - | 连接模板名 |
|
|
805
|
+
| `env` | object | - | 环境变量 |
|
|
806
|
+
| `defaultEnv` | object | - | 连接级默认环境变量 |
|
|
807
|
+
| `runAs` | string | - | 默认执行用户 |
|
|
808
|
+
| `keepaliveInterval` | number | 30000 | 心跳间隔(毫秒) |
|
|
809
|
+
| `readyTimeout` | number | 30000 | 等待 SSH ready 的超时,最大 600000 毫秒 |
|
|
810
|
+
| `jumpHost.readyTimeout` | number | 继承顶层值 | 跳板机等待 SSH ready 的超时,最大 600000 毫秒 |
|
|
628
811
|
|
|
629
812
|
连接失败返回 `failureStage`、`retryable` 和限量建议,`failureStage` 为 `preflight`、`authentication`、`ready_timeout`、
|
|
630
813
|
`transport_or_handshake` 或 `unknown`,多跳连接还可能返回 `connectionStep`,取值为 `key_read`、`jump_connect`、
|
|
@@ -632,16 +815,16 @@ forward,避免 ssh2 pending channel 继续累积,此时断开 alias 才能
|
|
|
632
815
|
|
|
633
816
|
### 执行选项
|
|
634
817
|
|
|
635
|
-
| 选项 | 类型 | 默认值 | 描述
|
|
636
|
-
| --------------- | ------- | ------------ |
|
|
637
|
-
| `timeout` | number | 30000 | 命令超时(毫秒)
|
|
638
|
-
| `cwd` | string | - | 工作目录
|
|
639
|
-
| `env` | object | - | 额外环境变量
|
|
640
|
-
| `pty` | boolean | false | 启用 PTY 模式(用于交互式命令)
|
|
641
|
-
| `maxOutputSize` | number | 10
|
|
642
|
-
| `runAs` | string | 连接级 runAs | 本次命令执行用户
|
|
643
|
-
| `useLoginUser` | boolean | false | 跳过连接级 runAs
|
|
644
|
-
| `loadProfile` | boolean | true | runAs 时加载目标用户 shell 配置
|
|
818
|
+
| 选项 | 类型 | 默认值 | 描述 |
|
|
819
|
+
| --------------- | ------- | ------------ | ----------------------------------- |
|
|
820
|
+
| `timeout` | number | 30000 | 命令超时(毫秒) |
|
|
821
|
+
| `cwd` | string | - | 工作目录 |
|
|
822
|
+
| `env` | object | - | 额外环境变量 |
|
|
823
|
+
| `pty` | boolean | false | 启用 PTY 模式(用于交互式命令) |
|
|
824
|
+
| `maxOutputSize` | number | 10 MiB 字节 | stdout/stderr 各自的 UTF-8 字节上限 |
|
|
825
|
+
| `runAs` | string | 连接级 runAs | 本次命令执行用户 |
|
|
826
|
+
| `useLoginUser` | boolean | false | 跳过连接级 runAs |
|
|
827
|
+
| `loadProfile` | boolean | true | runAs 时加载目标用户 shell 配置 |
|
|
645
828
|
|
|
646
829
|
传入 `cwd` 或 `env` 时,生成的 shell 命令会用 `&&` 连接 `cd` 和每个通过校验的
|
|
647
830
|
`export`,再把完整用户命令作为当前登录 shell 的一个转义后 `eval`
|
package/dist/command-risk.d.ts
CHANGED
|
@@ -1,7 +1,8 @@
|
|
|
1
|
+
import type { CommandShell } from './types.js';
|
|
1
2
|
export type CommandRisk = {
|
|
2
3
|
level: 'medium' | 'high';
|
|
3
4
|
categories: string[];
|
|
4
5
|
signals: string[];
|
|
5
6
|
suggestion: string;
|
|
6
7
|
};
|
|
7
|
-
export declare function classifyCommandRisk(command: string, timeout?: number): CommandRisk | undefined;
|
|
8
|
+
export declare function classifyCommandRisk(command: string, timeout?: number, shell?: CommandShell): CommandRisk | undefined;
|