@pyrokine/mcp-ssh 2.3.2 → 2.4.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 +94 -20
- package/README_zh.md +64 -19
- package/dist/command-risk.d.ts +7 -0
- package/dist/command-risk.js +106 -0
- package/dist/directory-verification.d.ts +43 -0
- package/dist/directory-verification.js +485 -0
- package/dist/file-ops.d.ts +56 -13
- package/dist/file-ops.js +531 -145
- package/dist/forward-manager.d.ts +5 -2
- package/dist/forward-manager.js +133 -19
- package/dist/index.js +2 -1
- package/dist/operation-manager.d.ts +52 -0
- package/dist/operation-manager.js +402 -0
- package/dist/pty-manager.d.ts +1 -0
- package/dist/pty-manager.js +11 -7
- package/dist/session-manager.d.ts +21 -10
- package/dist/session-manager.js +328 -75
- package/dist/tools/connection.js +48 -8
- package/dist/tools/exec.js +7 -66
- package/dist/tools/file.js +455 -81
- package/dist/tools/forward.js +12 -4
- package/dist/tools/index.d.ts +1 -0
- package/dist/tools/index.js +1 -0
- package/dist/tools/operation.d.ts +2 -0
- package/dist/tools/operation.js +126 -0
- package/dist/tools/utils.d.ts +2 -2
- package/dist/transfer-outcome.d.ts +12 -0
- package/dist/transfer-outcome.js +72 -0
- package/dist/types.d.ts +94 -6
- package/package.json +10 -8
package/README.md
CHANGED
|
@@ -96,7 +96,7 @@ Add to your MCP settings (e.g., `~/.claude/settings.json` or client-specific con
|
|
|
96
96
|
}
|
|
97
97
|
```
|
|
98
98
|
|
|
99
|
-
## Available Tools (
|
|
99
|
+
## Available Tools (35 tools)
|
|
100
100
|
|
|
101
101
|
### Connection Management
|
|
102
102
|
|
|
@@ -104,10 +104,12 @@ Add to your MCP settings (e.g., `~/.claude/settings.json` or client-specific con
|
|
|
104
104
|
|---------------------|---------------------------------------------------|
|
|
105
105
|
| `ssh_connect` | Establish SSH connection (supports ~/.ssh/config) |
|
|
106
106
|
| `ssh_disconnect` | Close connection |
|
|
107
|
-
| `ssh_list_sessions` | List
|
|
107
|
+
| `ssh_list_sessions` | List brief sessions; optional detail/field selection |
|
|
108
108
|
| `ssh_reconnect` | Reconnect a disconnected session |
|
|
109
109
|
| `ssh_config_list` | List hosts from ~/.ssh/config |
|
|
110
110
|
|
|
111
|
+
`ssh_list_sessions()` returns only `alias`, canonical `identity`, `runAs`, `connected`, and `lastUsedAt`. Use `detail=true` for connection details or `fields=[...]` to select fields. Neither mode returns `keyPath`.
|
|
112
|
+
|
|
111
113
|
### Command Execution
|
|
112
114
|
|
|
113
115
|
| Tool | Description |
|
|
@@ -120,6 +122,16 @@ Add to your MCP settings (e.g., `~/.claude/settings.json` or client-specific con
|
|
|
120
122
|
| `ssh_quick_exec` | One-shot: connect, execute, disconnect |
|
|
121
123
|
| `ssh_exec_script` | Upload and run a temporary remote script |
|
|
122
124
|
|
|
125
|
+
### Tracked operations
|
|
126
|
+
|
|
127
|
+
| Tool | Description |
|
|
128
|
+
|------------------------|--------------------------------------------------|
|
|
129
|
+
| `ssh_operation_start` | Start a tracked long-running remote command |
|
|
130
|
+
| `ssh_operation_status` | Read status, PID, exit code, and output counters |
|
|
131
|
+
| `ssh_operation_read` | Read bounded stdout and stderr by byte offset |
|
|
132
|
+
| `ssh_operation_cancel` | Verify the operation marker, then send TERM |
|
|
133
|
+
| `ssh_operation_list` | List unexpired operations, optionally by alias |
|
|
134
|
+
|
|
123
135
|
### File Operations
|
|
124
136
|
|
|
125
137
|
| Tool | Description |
|
|
@@ -283,6 +295,24 @@ Timeout errors include the same head/tail fields from output produced before the
|
|
|
283
295
|
process-control, service-control, credential-bearing, unbounded `find`, recursive `grep`, long pipelines, background
|
|
284
296
|
tasks, direct `su - user -c`, or long-running patterns return a `commandRisk` block with `categories` and `signals`.
|
|
285
297
|
|
|
298
|
+
### Tracked long-running commands
|
|
299
|
+
|
|
300
|
+
Use tracked operations when a command must continue beyond one synchronous tool call:
|
|
301
|
+
|
|
302
|
+
```
|
|
303
|
+
ssh_operation_start(alias="server", command="long-running-job", maxOutputBytes=1048576)
|
|
304
|
+
ssh_operation_status(operationId="op_xxx")
|
|
305
|
+
ssh_operation_read(operationId="op_xxx", stdoutOffset=0, stderrOffset=0, maxBytes=65536)
|
|
306
|
+
ssh_operation_cancel(operationId="op_xxx")
|
|
307
|
+
```
|
|
308
|
+
|
|
309
|
+
The start call returns an unpredictable `operationId`. The server keeps bounded stdout and stderr buffers, records the
|
|
310
|
+
remote PID after verifying a per-operation marker, and expires completed records after `retentionMs`. `maxOutputBytes`
|
|
311
|
+
defaults to 1 MiB and accepts up to 8 MiB. `retentionMs` defaults to 1 hour and accepts up to 24 hours.
|
|
312
|
+
`ssh_operation_read.maxBytes` defaults to 64 KiB and accepts up to 1 MiB. Cancellation is refused until the marker and
|
|
313
|
+
PID are verified. If the SSH session disconnects while the command is active, its status becomes `unknown`; the server
|
|
314
|
+
does not claim that the remote process stopped. `ssh_exec` keeps its existing synchronous timeout behavior.
|
|
315
|
+
|
|
286
316
|
### Interactive Commands (PTY mode)
|
|
287
317
|
|
|
288
318
|
For commands that need a terminal:
|
|
@@ -353,8 +383,9 @@ ssh_read_file(alias="server", remotePath="/var/log/app.log", lineRange="120-180"
|
|
|
353
383
|
```
|
|
354
384
|
|
|
355
385
|
`ssh_upload` returns local path policy diagnostics, remote parent probing, remote target metadata, and optional
|
|
356
|
-
verification checks. `atomic=true` uploads to a same-directory temporary file,
|
|
357
|
-
`verifySize`, `verifyMd5`, `verifyMode`, `verifyOwner`, and `verifyMtime` add explicit
|
|
386
|
+
verification checks. `atomic=true` uploads to a same-directory temporary file, returns `diagnostics.tempRemotePath`,
|
|
387
|
+
then renames it to the target path. `verifySize`, `verifyMd5`, `verifyMode`, `verifyOwner`, and `verifyMtime` add explicit
|
|
388
|
+
post-transfer checks.
|
|
358
389
|
Command execution results include `emptyOutputFailure=true` when the remote command exits non-zero without
|
|
359
390
|
stdout/stderr,
|
|
360
391
|
with the effective user, cwd, and a suggested follow-up read command when available.
|
|
@@ -362,9 +393,9 @@ with the effective user, cwd, and a suggested follow-up read command when availa
|
|
|
362
393
|
`read_offset`, `read_bytes`, `remaining_bytes`, `sample_kind`, and `truncated` so callers can distinguish a full read
|
|
363
394
|
from a head, tail, byte range, or line range sample.
|
|
364
395
|
|
|
365
|
-
### Directory
|
|
396
|
+
### Directory sync with rsync or SFTP
|
|
366
397
|
|
|
367
|
-
Smart sync
|
|
398
|
+
Smart sync selects rsync only for a direct connection with a validated key path or usable SSH agent. Password, inline-key, jump-host, and other routes that cannot be passed safely to OpenSSH use SFTP directly:
|
|
368
399
|
|
|
369
400
|
```
|
|
370
401
|
// Sync local directory to remote (upload)
|
|
@@ -374,7 +405,7 @@ ssh_sync(
|
|
|
374
405
|
remotePath="/remote/project",
|
|
375
406
|
direction="upload"
|
|
376
407
|
)
|
|
377
|
-
// Returns
|
|
408
|
+
// Returns selectedTransport, decisionReason, stage durations, and transfer counters
|
|
378
409
|
|
|
379
410
|
// Sync with exclude patterns
|
|
380
411
|
ssh_sync(
|
|
@@ -398,16 +429,44 @@ ssh_sync(..., dryRun=true)
|
|
|
398
429
|
|
|
399
430
|
// Upload one file and verify remote owner/mode after transfer
|
|
400
431
|
ssh_sync(..., direction="upload", verifyOwner="appuser", verifyMode="0644")
|
|
401
|
-
```
|
|
402
432
|
|
|
403
|
-
|
|
404
|
-
|
|
405
|
-
|
|
406
|
-
|
|
407
|
-
|
|
433
|
+
// Verify a directory with bounded manifests
|
|
434
|
+
ssh_sync(
|
|
435
|
+
...,
|
|
436
|
+
verify={count: true, sha256: true, owner: true, mode: true, staleFiles: true}
|
|
437
|
+
)
|
|
408
438
|
|
|
409
|
-
|
|
410
|
-
|
|
439
|
+
// Verify that entries present before --delete were removed
|
|
440
|
+
ssh_sync(..., delete=true, verify={deletions: true})
|
|
441
|
+
```
|
|
442
|
+
|
|
443
|
+
A directory source always means “copy the source directory contents into the destination root” in both rsync and SFTP
|
|
444
|
+
mode. Directory sources reject `recursive=false`. Relative exclude patterns are evaluated against the path below the
|
|
445
|
+
source root; patterns without `/` match each basename.
|
|
446
|
+
|
|
447
|
+
Directory verification builds bounded local and remote manifests. It can compare entry count, a SHA-256 root manifest,
|
|
448
|
+
owner, mode, stale entries, and deletion results. `verify.deletions=true` requires `delete=true`; it records the destination
|
|
449
|
+
before transfer and only checks whether those deletion candidates disappeared. `staleFiles` independently checks every
|
|
450
|
+
extra destination entry. The response contains summaries and at most 20 mismatch samples, not the full manifest. The
|
|
451
|
+
default limits are 10,000 entries, 256 MiB per hashed file, and 1 GiB total hashed bytes. Set `verify.maxEntries`,
|
|
452
|
+
`verify.maxFileBytes`, and `verify.maxTotalBytes` to raise them, up to 50,000 entries, 4 GiB per file, and 16 GiB total.
|
|
453
|
+
Symlinks or unsupported filesystem entries that were skipped make verification explicitly `skipped` instead of
|
|
454
|
+
reporting a partial match.
|
|
455
|
+
|
|
456
|
+
If verification is requested, a mismatch, skipped check, or verification error sets top-level `success=false` while
|
|
457
|
+
`transferSuccess` still reports whether transfer completed. `verificationStatus`, `verificationSuccess`, and
|
|
458
|
+
`failedChecks` describe the verification outcome. SFTP single-file transfers also include local and remote size,
|
|
459
|
+
mode or permissions, mtime, owner/group, and SHA-256 comparison when the remote has `sha256sum`. `verifyOwner` and
|
|
460
|
+
`verifyMode` apply to upload single-file sync; use `verify.owner` and `verify.mode` for directory manifests.
|
|
461
|
+
|
|
462
|
+
Rsync is selected only for a direct connection with a validated key path or usable SSH agent. Password, inline-key, and
|
|
463
|
+
jump-host sessions use SFTP because their route or credentials cannot be passed safely to a separate OpenSSH process.
|
|
464
|
+
`preflightTimeout`, `connectTimeout`, and `operationTimeout` independently bound capability probing, rsync SSH setup, and
|
|
465
|
+
the overall transfer; their defaults are 10 seconds, 30 seconds, and 10 minutes. When the session is not eligible for
|
|
466
|
+
rsync, the response returns `rsyncProbe.status="skipped"` with the route decision reason instead of omitting the probe.
|
|
467
|
+
Rsync mode sets
|
|
468
|
+
`StrictHostKeyChecking=accept-new`. SFTP does not support `delete=true`; such a request fails explicitly instead of
|
|
469
|
+
claiming deletion. If you require strict host key verification and management, use SFTP mode.
|
|
411
470
|
|
|
412
471
|
### Persistent PTY Sessions (top, tmux, etc.)
|
|
413
472
|
|
|
@@ -447,6 +506,8 @@ ssh_pty_write(ptyId="pty_1_xxx", data="\x02d")
|
|
|
447
506
|
|
|
448
507
|
`ssh_pty_read` and `ssh_pty_list` expose `lastInputAt`, `lastOutputAt`, `lastReadAt`, `unreadRawBytes`,
|
|
449
508
|
`rawBufferLimit`, and `foregroundProcess` so long-running sessions can be monitored without reading the full raw stream.
|
|
509
|
+
When a finite command exits naturally, its final screen remains readable with `active=false` until explicit close or the
|
|
510
|
+
closed-session retention expires (5 minutes by default, configurable with `SSH_MCP_PTY_CLOSED_RETENTION_MS`).
|
|
450
511
|
|
|
451
512
|
Common control sequences:
|
|
452
513
|
|
|
@@ -471,10 +532,18 @@ ssh_forward_remote(alias="server", remotePort=8080, localHost="127.0.0.1", local
|
|
|
471
532
|
// List all forwards
|
|
472
533
|
ssh_forward_list()
|
|
473
534
|
|
|
474
|
-
// Close
|
|
475
|
-
ssh_forward_close(forwardId="fwd_1_xxx")
|
|
535
|
+
// Close after the listener is released
|
|
536
|
+
ssh_forward_close(forwardId="fwd_1_xxx", mode="graceful", timeoutMs=5000)
|
|
537
|
+
|
|
538
|
+
// Destroy active connections, then release the listener
|
|
539
|
+
ssh_forward_close(forwardId="fwd_1_xxx", mode="force", timeoutMs=5000)
|
|
476
540
|
```
|
|
477
541
|
|
|
542
|
+
A successful close means the local `server.close` or remote `unforwardIn` callback completed. The result includes
|
|
543
|
+
`listenerReleased`, `remoteUnforwarded`, `activeConnections`, `closeMode`, and `retryable`. Timeout or callback failure
|
|
544
|
+
keeps the forward in `ssh_forward_list`, so the same `forwardId` can be retried. After a successful local close, the port
|
|
545
|
+
can be rebound immediately.
|
|
546
|
+
|
|
478
547
|
## Configuration Options
|
|
479
548
|
|
|
480
549
|
### Connection Options
|
|
@@ -492,6 +561,10 @@ ssh_forward_close(forwardId="fwd_1_xxx")
|
|
|
492
561
|
| `defaultEnv` | object | - | Default env for this session |
|
|
493
562
|
| `runAs` | string | - | Default execution user |
|
|
494
563
|
| `keepaliveInterval` | number | 30000 | Keepalive interval in ms |
|
|
564
|
+
| `readyTimeout` | number | 30000 | Wait for SSH ready in ms, max 600000 |
|
|
565
|
+
| `jumpHost.readyTimeout` | number | top-level value | Jump-host ready timeout, max 600000 |
|
|
566
|
+
|
|
567
|
+
Connection failures return `failureStage`, `retryable`, and a bounded suggestion. `failureStage` is one of `preflight`, `authentication`, `ready_timeout`, `transport_or_handshake`, or `unknown`; multi-hop failures may also include `connectionStep` as `key_read`, `jump_connect`, `jump_forward`, or `target_connect`.
|
|
495
568
|
|
|
496
569
|
### Exec Options
|
|
497
570
|
|
|
@@ -550,11 +623,12 @@ Files exceeding these limits are rejected before being read.
|
|
|
550
623
|
|
|
551
624
|
| `followSymlinks` | SFTP path | rsync path |
|
|
552
625
|
|-------------------|------------------------------------------------------------|-----------------------------------------------------------------------------|
|
|
553
|
-
| `false` (default) | Skipped, returned in `skippedSymlinks`, printed as warning |
|
|
626
|
+
| `false` (default) | Skipped, returned in `skippedSymlinks`, printed as warning | Skipped via `--no-links` |
|
|
554
627
|
| `true` | Followed: link target contents are uploaded | Followed via rsync `-L` / `--copy-links`: link target contents are uploaded |
|
|
555
628
|
|
|
556
|
-
Both
|
|
557
|
-
|
|
629
|
+
Both transports skip device and special filesystem entries. SFTP returns `skippedUnsupported` and up to 10 sample paths;
|
|
630
|
+
rsync uses `--no-devices --no-specials`. Directory verification also reports skipped symlinks and unsupported entries and
|
|
631
|
+
does not treat an incomplete manifest as a match.
|
|
558
632
|
|
|
559
633
|
## Project Structure
|
|
560
634
|
|
package/README_zh.md
CHANGED
|
@@ -96,7 +96,7 @@ claude mcp add ssh -- node /path/to/mcp-ssh/dist/index.js
|
|
|
96
96
|
}
|
|
97
97
|
```
|
|
98
98
|
|
|
99
|
-
## 可用工具(
|
|
99
|
+
## 可用工具(35 个)
|
|
100
100
|
|
|
101
101
|
### 连接管理
|
|
102
102
|
|
|
@@ -104,10 +104,12 @@ claude mcp add ssh -- node /path/to/mcp-ssh/dist/index.js
|
|
|
104
104
|
|---------------------|-----------------------------|
|
|
105
105
|
| `ssh_connect` | 建立 SSH 连接(支持 ~/.ssh/config) |
|
|
106
106
|
| `ssh_disconnect` | 关闭连接 |
|
|
107
|
-
| `ssh_list_sessions` |
|
|
107
|
+
| `ssh_list_sessions` | 列出精简会话,可选详情或字段筛选 |
|
|
108
108
|
| `ssh_reconnect` | 重新连接断开的会话 |
|
|
109
109
|
| `ssh_config_list` | 列出 ~/.ssh/config 中的 Host |
|
|
110
110
|
|
|
111
|
+
`ssh_list_sessions()` 默认只返回 `alias`、规范化 `identity`、`runAs`、`connected` 和 `lastUsedAt`,使用 `detail=true` 获取连接详情,或通过 `fields=[...]` 选择字段,任何模式都不返回 `keyPath`
|
|
112
|
+
|
|
111
113
|
### 命令执行
|
|
112
114
|
|
|
113
115
|
| 工具 | 描述 |
|
|
@@ -120,6 +122,16 @@ claude mcp add ssh -- node /path/to/mcp-ssh/dist/index.js
|
|
|
120
122
|
| `ssh_quick_exec` | 一次性执行:连接、执行、断开 |
|
|
121
123
|
| `ssh_exec_script` | 上传并执行远端临时脚本 |
|
|
122
124
|
|
|
125
|
+
### 可跟踪任务
|
|
126
|
+
|
|
127
|
+
| 工具 | 描述 |
|
|
128
|
+
|------------------------|------------------------------|
|
|
129
|
+
| `ssh_operation_start` | 启动可跟踪的长时间远端命令 |
|
|
130
|
+
| `ssh_operation_status` | 读取状态、PID、退出码和输出计数 |
|
|
131
|
+
| `ssh_operation_read` | 按字节偏移读取有上限的 stdout 和 stderr |
|
|
132
|
+
| `ssh_operation_cancel` | 校验任务 marker 后发送 TERM |
|
|
133
|
+
| `ssh_operation_list` | 列出未过期任务,可按 alias 过滤 |
|
|
134
|
+
|
|
123
135
|
### 文件操作
|
|
124
136
|
|
|
125
137
|
| 工具 | 描述 |
|
|
@@ -279,6 +291,19 @@ ssh_connect(
|
|
|
279
291
|
destructive、process-control、service-control、credential-bearing、未限制 `find`、递归 `grep`、长管道、后台任务、直接
|
|
280
292
|
`su - user -c` 或长运行模式的命令会返回带 `categories` 和 `signals` 的 `commandRisk`
|
|
281
293
|
|
|
294
|
+
### 可跟踪的长时间命令
|
|
295
|
+
|
|
296
|
+
需要命令跨越一次同步工具调用继续执行时,使用 operation 工具组:
|
|
297
|
+
|
|
298
|
+
```
|
|
299
|
+
ssh_operation_start(alias="server", command="long-running-job", maxOutputBytes=1048576)
|
|
300
|
+
ssh_operation_status(operationId="op_xxx")
|
|
301
|
+
ssh_operation_read(operationId="op_xxx", stdoutOffset=0, stderrOffset=0, maxBytes=65536)
|
|
302
|
+
ssh_operation_cancel(operationId="op_xxx")
|
|
303
|
+
```
|
|
304
|
+
|
|
305
|
+
start 返回不可预测的 `operationId`,服务端保存有硬上限的 stdout 和 stderr,在校验每个任务独立的 marker 后记录远端 PID,`maxOutputBytes` 默认 1 MiB、最大 8 MiB,`retentionMs` 默认 1 小时、最大 24 小时,`ssh_operation_read.maxBytes` 默认 64 KiB、最大 1 MiB,marker 和 PID 未完成校验时拒绝取消,SSH 会话在任务运行期间断开后状态变为 `unknown`,不会声称远端进程已经停止,`ssh_exec` 保持原有同步 timeout 行为
|
|
306
|
+
|
|
282
307
|
### 交互式命令(PTY 模式)
|
|
283
308
|
|
|
284
309
|
用于需要终端的命令:
|
|
@@ -348,16 +373,16 @@ ssh_read_file(alias="server", remotePath="/var/log/app.log", offset=1048576, max
|
|
|
348
373
|
ssh_read_file(alias="server", remotePath="/var/log/app.log", lineRange="120-180")
|
|
349
374
|
```
|
|
350
375
|
|
|
351
|
-
`ssh_upload` 返回本地路径策略诊断、远端父目录探测、远端目标元数据和可选校验结果,`atomic=true`
|
|
352
|
-
rename 到目标路径,`verifySize`、`verifyMd5`、`verifyMode`、`verifyOwner`、`verifyMtime` 会追加显式传输后校验,命令执行结果在远端命令非零退出且没有
|
|
376
|
+
`ssh_upload` 返回本地路径策略诊断、远端父目录探测、远端目标元数据和可选校验结果,`atomic=true` 会先上传到同目录临时文件,返回
|
|
377
|
+
`diagnostics.tempRemotePath` 后再 rename 到目标路径,`verifySize`、`verifyMd5`、`verifyMode`、`verifyOwner`、`verifyMtime` 会追加显式传输后校验,命令执行结果在远端命令非零退出且没有
|
|
353
378
|
stdout/stderr 时返回
|
|
354
379
|
`emptyOutputFailure=true`,同时给出 effective user、cwd 和可用的后续读取建议,`ssh_read_file` 默认读取 1 MiB,`maxBytes` 超过
|
|
355
380
|
16 MiB 时会在远端传输前拒绝,返回 `total_size`、`read_offset`、`read_bytes`、
|
|
356
381
|
`remaining_bytes`、`sample_kind` 和 `truncated`,调用方可以区分完整读取、头部样本、尾部样本、字节范围和行范围
|
|
357
382
|
|
|
358
|
-
###
|
|
383
|
+
### 使用 rsync 或 SFTP 同步目录
|
|
359
384
|
|
|
360
|
-
|
|
385
|
+
智能同步只在直连且存在已校验 key path 或可用 SSH agent 时选择 rsync,password、inline key、jump host 和其他无法安全交给 OpenSSH 的路由直接使用 SFTP:
|
|
361
386
|
|
|
362
387
|
```
|
|
363
388
|
// 同步本地目录到远程(上传)
|
|
@@ -367,7 +392,7 @@ ssh_sync(
|
|
|
367
392
|
remotePath="/remote/project",
|
|
368
393
|
direction="upload"
|
|
369
394
|
)
|
|
370
|
-
//
|
|
395
|
+
// 返回 selectedTransport、decisionReason、各阶段耗时和传输计数
|
|
371
396
|
|
|
372
397
|
// 带排除模式
|
|
373
398
|
ssh_sync(
|
|
@@ -391,16 +416,24 @@ ssh_sync(..., dryRun=true)
|
|
|
391
416
|
|
|
392
417
|
// 上传单文件后校验远端 owner/mode
|
|
393
418
|
ssh_sync(..., direction="upload", verifyOwner="appuser", verifyMode="0644")
|
|
419
|
+
|
|
420
|
+
// 使用有界 manifest 校验目录
|
|
421
|
+
ssh_sync(
|
|
422
|
+
...,
|
|
423
|
+
verify={count: true, sha256: true, owner: true, mode: true, staleFiles: true}
|
|
424
|
+
)
|
|
425
|
+
|
|
426
|
+
// 校验传输前存在且应由 --delete 删除的条目已经消失
|
|
427
|
+
ssh_sync(..., delete=true, verify={deletions: true})
|
|
394
428
|
```
|
|
395
429
|
|
|
396
|
-
|
|
397
|
-
|
|
398
|
-
|
|
399
|
-
`verifyOwner` 和 `verifyMode` 追加基于远端元数据的 `ownerMode` 校验,目录同步不递归扫描 owner/mode,会返回 skipped
|
|
400
|
-
verification 说明
|
|
430
|
+
目录源路径在 rsync 和 SFTP 模式下都表示“把源目录内容同步到目标根目录”,目录源使用 `recursive=false` 会被明确拒绝,相对排除模式按源目录下的相对路径匹配,不含 `/` 的模式匹配每一级 basename
|
|
431
|
+
|
|
432
|
+
目录校验会生成有界的本地和远端 manifest,可比较条目数、SHA-256 root manifest、owner、mode、旧文件和删除结果,`verify.deletions=true` 必须同时设置 `delete=true`,工具会在传输前记录目标目录,只检查这些删除候选是否消失,`staleFiles` 则独立检查目标端全部额外条目,响应只返回摘要和最多 20 个 mismatch 样本,不返回完整 manifest,默认上限为 10000 个条目、单文件 256 MiB、总哈希字节 1 GiB,可通过 `verify.maxEntries`、`verify.maxFileBytes` 和 `verify.maxTotalBytes` 提高到最多 50000 个条目、单文件 4 GiB、总哈希字节 16 GiB,遇到被跳过的 symlink 或不支持的文件系统条目时,校验会明确返回 `skipped`,不会报告部分匹配成功
|
|
401
433
|
|
|
402
|
-
|
|
403
|
-
|
|
434
|
+
请求校验后,mismatch、skipped 或校验错误都会令顶层 `success=false`,`transferSuccess` 仍单独表示传输是否完成,`verificationStatus`、`verificationSuccess` 和 `failedChecks` 描述校验结果,SFTP 单文件同步还会返回本地和远端的 size、mode 或 permissions、mtime、owner/group,以及远端支持 `sha256sum` 时的 SHA-256 对比,upload 单文件使用 `verifyOwner` 和 `verifyMode`,目录逐项校验使用 `verify.owner` 和 `verify.mode`
|
|
435
|
+
|
|
436
|
+
只有直连且存在已校验 key path 或可用 SSH agent 时才选择 rsync,password、inline key 和 jump host 会使用 SFTP,因为独立 OpenSSH 进程无法安全继承对应路由或认证材料,`preflightTimeout`、`connectTimeout` 和 `operationTimeout` 分别限制能力预检、rsync SSH 建连和完整传输,默认值为 10 秒、30 秒和 10 分钟,不具备 rsync 条件的 session 会返回 `rsyncProbe.status="skipped"` 和路由判定原因,不再省略 probe,rsync 模式设置 `StrictHostKeyChecking=accept-new`,SFTP 不支持 `delete=true`,此类请求会明确失败,不会报告已经删除,如需严格的主机密钥验证与管理,请使用 SFTP 模式
|
|
404
437
|
|
|
405
438
|
### 持久化 PTY 会话(top、tmux 等)
|
|
406
439
|
|
|
@@ -439,7 +472,8 @@ ssh_pty_write(ptyId="pty_1_xxx", data="\x02d")
|
|
|
439
472
|
```
|
|
440
473
|
|
|
441
474
|
`ssh_pty_read` 和 `ssh_pty_list` 返回 `lastInputAt`、`lastOutputAt`、`lastReadAt`、`unreadRawBytes`、`rawBufferLimit`、
|
|
442
|
-
`foregroundProcess`,便于观察长时间运行的会话,无需读取完整 raw
|
|
475
|
+
`foregroundProcess`,便于观察长时间运行的会话,无需读取完整 raw 流,有限命令自然结束后仍可读取最终 screen,返回 `active=false`,
|
|
476
|
+
直到显式 close 或 closed session 保留期结束,默认 5 分钟,可通过 `SSH_MCP_PTY_CLOSED_RETENTION_MS` 调整
|
|
443
477
|
|
|
444
478
|
常用控制序列:
|
|
445
479
|
|
|
@@ -464,10 +498,17 @@ ssh_forward_remote(alias="server", remotePort=8080, localHost="127.0.0.1", local
|
|
|
464
498
|
// 列出所有转发
|
|
465
499
|
ssh_forward_list()
|
|
466
500
|
|
|
467
|
-
//
|
|
468
|
-
ssh_forward_close(forwardId="fwd_1_xxx")
|
|
501
|
+
// listener 释放后返回成功
|
|
502
|
+
ssh_forward_close(forwardId="fwd_1_xxx", mode="graceful", timeoutMs=5000)
|
|
503
|
+
|
|
504
|
+
// 销毁活跃连接后释放 listener
|
|
505
|
+
ssh_forward_close(forwardId="fwd_1_xxx", mode="force", timeoutMs=5000)
|
|
469
506
|
```
|
|
470
507
|
|
|
508
|
+
关闭成功表示本地 `server.close` 或远端 `unforwardIn` callback 已完成,结果包含 `listenerReleased`、
|
|
509
|
+
`remoteUnforwarded`、`activeConnections`、`closeMode` 和 `retryable`,超时或 callback 失败时 forward 仍保留在
|
|
510
|
+
`ssh_forward_list`,可以使用同一 `forwardId` 重试,本地转发关闭成功后端口可立即重新 bind
|
|
511
|
+
|
|
471
512
|
## 配置选项
|
|
472
513
|
|
|
473
514
|
### 连接选项
|
|
@@ -485,6 +526,10 @@ ssh_forward_close(forwardId="fwd_1_xxx")
|
|
|
485
526
|
| `defaultEnv` | object | - | 连接级默认环境变量 |
|
|
486
527
|
| `runAs` | string | - | 默认执行用户 |
|
|
487
528
|
| `keepaliveInterval` | number | 30000 | 心跳间隔(毫秒) |
|
|
529
|
+
| `readyTimeout` | number | 30000 | 等待 SSH ready 的超时,最大 600000 毫秒 |
|
|
530
|
+
| `jumpHost.readyTimeout` | number | 继承顶层值 | 跳板机等待 SSH ready 的超时,最大 600000 毫秒 |
|
|
531
|
+
|
|
532
|
+
连接失败返回 `failureStage`、`retryable` 和限量建议,`failureStage` 为 `preflight`、`authentication`、`ready_timeout`、`transport_or_handshake` 或 `unknown`,多跳连接还可能返回 `connectionStep`,取值为 `key_read`、`jump_connect`、`jump_forward` 或 `target_connect`
|
|
488
533
|
|
|
489
534
|
### 执行选项
|
|
490
535
|
|
|
@@ -540,10 +585,10 @@ export SSH_MCP_FILE_OPS_ALLOW_DIRS=/tmp:/home/me/work
|
|
|
540
585
|
|
|
541
586
|
| `followSymlinks` | SFTP 路径 | rsync 路径 |
|
|
542
587
|
|------------------|----------------------------------------|--------------------------------------------|
|
|
543
|
-
| `false`(默认) | 跳过,写入 `skippedSymlinks` 字段,warning 中提示 |
|
|
588
|
+
| `false`(默认) | 跳过,写入 `skippedSymlinks` 字段,warning 中提示 | 通过 `--no-links` 跳过 |
|
|
544
589
|
| `true` | 跟随:上传链接目标内容 | 通过 rsync `-L` / `--copy-links` 跟随:上传链接目标内容 |
|
|
545
590
|
|
|
546
|
-
|
|
591
|
+
两种传输都会跳过 device 和特殊文件系统条目,SFTP 返回 `skippedUnsupported` 和最多 10 个样本路径,rsync 使用 `--no-devices --no-specials`,目录校验也会报告被跳过的 symlink 和不支持条目,不会把不完整 manifest 当成匹配成功
|
|
547
592
|
|
|
548
593
|
## 项目结构
|
|
549
594
|
|
|
@@ -0,0 +1,106 @@
|
|
|
1
|
+
function pushRisk(categories, signals, category, signal) {
|
|
2
|
+
categories.add(category);
|
|
3
|
+
signals.push(signal);
|
|
4
|
+
}
|
|
5
|
+
function hasBackgroundOperator(command) {
|
|
6
|
+
let quote;
|
|
7
|
+
let escaped = false;
|
|
8
|
+
for (let index = 0; index < command.length; ++index) {
|
|
9
|
+
const character = command[index];
|
|
10
|
+
if (escaped) {
|
|
11
|
+
escaped = false;
|
|
12
|
+
continue;
|
|
13
|
+
}
|
|
14
|
+
if (character === '\\' && quote !== "'") {
|
|
15
|
+
escaped = true;
|
|
16
|
+
continue;
|
|
17
|
+
}
|
|
18
|
+
if (quote) {
|
|
19
|
+
if (character === quote) {
|
|
20
|
+
quote = undefined;
|
|
21
|
+
}
|
|
22
|
+
continue;
|
|
23
|
+
}
|
|
24
|
+
if (character === "'" || character === '"') {
|
|
25
|
+
quote = character;
|
|
26
|
+
continue;
|
|
27
|
+
}
|
|
28
|
+
if (character !== '&') {
|
|
29
|
+
continue;
|
|
30
|
+
}
|
|
31
|
+
const previous = command[index - 1];
|
|
32
|
+
const next = command[index + 1];
|
|
33
|
+
if (previous === '&' || next === '&' || previous === '>' || previous === '<' || next === '>') {
|
|
34
|
+
continue;
|
|
35
|
+
}
|
|
36
|
+
return true;
|
|
37
|
+
}
|
|
38
|
+
return false;
|
|
39
|
+
}
|
|
40
|
+
export function classifyCommandRisk(command, timeout) {
|
|
41
|
+
const signals = [];
|
|
42
|
+
const categories = new Set();
|
|
43
|
+
const pipeCount = (command.match(/\|/g) ?? []).length;
|
|
44
|
+
const lowerCommand = command.toLowerCase();
|
|
45
|
+
const background = hasBackgroundOperator(command);
|
|
46
|
+
const continuous = /\b(?:tail\s+-f|journalctl\s+-f|watch|top|htop)\b/.test(command);
|
|
47
|
+
const unboundedFind = /\bfind\b/.test(command) && !/\s-maxdepth\s+\d+/.test(command);
|
|
48
|
+
const recursiveGrep = /\bgrep\s+(?:-\S*R|--recursive)\b/.test(command);
|
|
49
|
+
if (command.length > 500) {
|
|
50
|
+
pushRisk(categories, signals, 'complexity-signal', 'long_command');
|
|
51
|
+
}
|
|
52
|
+
if (pipeCount >= 3) {
|
|
53
|
+
pushRisk(categories, signals, 'complexity-signal', 'long_pipeline');
|
|
54
|
+
}
|
|
55
|
+
if (recursiveGrep) {
|
|
56
|
+
pushRisk(categories, signals, 'long-running', 'recursive_grep');
|
|
57
|
+
}
|
|
58
|
+
if (unboundedFind) {
|
|
59
|
+
pushRisk(categories, signals, 'long-running', 'unbounded_find');
|
|
60
|
+
}
|
|
61
|
+
if (/\b(?:python|python3|node|perl|ruby)\b/.test(command)) {
|
|
62
|
+
pushRisk(categories, signals, 'script-execution', 'interpreter_script');
|
|
63
|
+
}
|
|
64
|
+
if (/\bsleep\s+\d{2,}\b/.test(command) || continuous) {
|
|
65
|
+
pushRisk(categories, signals, 'long-running', continuous ? 'continuous_command' : 'long_sleep');
|
|
66
|
+
}
|
|
67
|
+
if (background) {
|
|
68
|
+
pushRisk(categories, signals, 'process-control', 'background_task');
|
|
69
|
+
}
|
|
70
|
+
const recursiveRemove = /\brm\b(?=[^\n;|&]*(?:\s-[a-z]*r[a-z]*\b|\s--recursive\b))/.test(lowerCommand);
|
|
71
|
+
if (recursiveRemove || /\b(?:dd\s+if=|mkfs|fdisk|parted|shutdown|reboot)\b/.test(lowerCommand)) {
|
|
72
|
+
pushRisk(categories, signals, 'destructive', 'destructive_command');
|
|
73
|
+
}
|
|
74
|
+
const processControl = /\b(?:pkill|killall)\b/.test(lowerCommand) || /\bkill\s+(?!-0(?:\s|$))/.test(lowerCommand);
|
|
75
|
+
if (processControl) {
|
|
76
|
+
pushRisk(categories, signals, 'process-control', 'process_control');
|
|
77
|
+
}
|
|
78
|
+
if (/\b(?:systemctl|service|docker|kubectl)\s+(?:restart|stop|kill|delete|rm|down)\b/.test(lowerCommand)) {
|
|
79
|
+
pushRisk(categories, signals, 'service-control', 'service_control');
|
|
80
|
+
}
|
|
81
|
+
if (/\b(?:password|passwd|token|authorization|cookie|secret|private[_-]?key)\b/i.test(command)) {
|
|
82
|
+
pushRisk(categories, signals, 'credential-bearing', 'credential_bearing');
|
|
83
|
+
}
|
|
84
|
+
if (/\bsu\s+-?\s*[a-zA-Z_][a-zA-Z0-9_-]*\s+-c\b/.test(command)) {
|
|
85
|
+
pushRisk(categories, signals, 'user-switch', 'direct_su_command');
|
|
86
|
+
}
|
|
87
|
+
if (signals.length === 0) {
|
|
88
|
+
return undefined;
|
|
89
|
+
}
|
|
90
|
+
const boundedTimeout = timeout !== undefined && timeout > 0 && timeout <= 300_000;
|
|
91
|
+
const high = categories.has('destructive') ||
|
|
92
|
+
categories.has('service-control') ||
|
|
93
|
+
categories.has('process-control') ||
|
|
94
|
+
continuous ||
|
|
95
|
+
((unboundedFind || recursiveGrep) && !boundedTimeout);
|
|
96
|
+
return {
|
|
97
|
+
level: high ? 'high' : 'medium',
|
|
98
|
+
categories: Array.from(categories),
|
|
99
|
+
signals,
|
|
100
|
+
suggestion: signals.includes('direct_su_command')
|
|
101
|
+
? '建议使用 ssh_exec 的 runAs 参数或 ssh_exec_as_user,避免手写 su 命令造成引用和环境加载差异'
|
|
102
|
+
: high
|
|
103
|
+
? '长任务使用 ssh_operation_start,交互命令使用 ssh_pty_start,破坏性操作执行前确认目标范围'
|
|
104
|
+
: '如输出较大,请设置 maxOutputSize 或重定向到远端文件后分块读取',
|
|
105
|
+
};
|
|
106
|
+
}
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
export declare const DIRECTORY_VERIFY_MAX_ENTRIES = 50000;
|
|
2
|
+
export declare const DIRECTORY_VERIFY_MAX_MISMATCHES = 20;
|
|
3
|
+
export declare const DIRECTORY_VERIFY_DEFAULT_MAX_FILE_BYTES: number;
|
|
4
|
+
export declare const DIRECTORY_VERIFY_DEFAULT_MAX_TOTAL_BYTES: number;
|
|
5
|
+
export declare const DIRECTORY_VERIFY_MAX_FILE_BYTES: number;
|
|
6
|
+
export declare const DIRECTORY_VERIFY_MAX_TOTAL_BYTES: number;
|
|
7
|
+
export type DirectoryVerifyRequest = {
|
|
8
|
+
count?: boolean;
|
|
9
|
+
sha256?: boolean;
|
|
10
|
+
owner?: boolean;
|
|
11
|
+
mode?: boolean;
|
|
12
|
+
deletions?: boolean;
|
|
13
|
+
staleFiles?: boolean;
|
|
14
|
+
maxEntries?: number;
|
|
15
|
+
maxFileBytes?: number;
|
|
16
|
+
maxTotalBytes?: number;
|
|
17
|
+
};
|
|
18
|
+
type ManifestEntry = {
|
|
19
|
+
path: string;
|
|
20
|
+
type: 'file' | 'directory';
|
|
21
|
+
size: number;
|
|
22
|
+
mode: string;
|
|
23
|
+
owner: string;
|
|
24
|
+
sha256?: string;
|
|
25
|
+
};
|
|
26
|
+
type DirectoryManifestLimitReason = 'entries' | 'file_bytes' | 'total_bytes';
|
|
27
|
+
export type DirectoryManifest = {
|
|
28
|
+
entries: ManifestEntry[];
|
|
29
|
+
count: number;
|
|
30
|
+
rootSha256: string;
|
|
31
|
+
limited: boolean;
|
|
32
|
+
limitReason?: DirectoryManifestLimitReason;
|
|
33
|
+
skippedSymlinks: number;
|
|
34
|
+
skippedUnsupported: number;
|
|
35
|
+
unsupportedSamples: string[];
|
|
36
|
+
};
|
|
37
|
+
export declare function matchesDirectoryExclude(relativePath: string, patterns: string[] | undefined): boolean;
|
|
38
|
+
export declare function createLocalDirectoryManifest(rootPath: string, request: DirectoryVerifyRequest, exclude?: string[], followSymlinks?: boolean): Promise<DirectoryManifest>;
|
|
39
|
+
export declare function createEmptyDirectoryManifest(): DirectoryManifest;
|
|
40
|
+
export declare function buildRemoteDirectoryManifestCommand(rootPath: string, request: DirectoryVerifyRequest, exclude?: string[], followSymlinks?: boolean): string;
|
|
41
|
+
export declare function parseRemoteDirectoryManifest(output: string): DirectoryManifest;
|
|
42
|
+
export declare function compareDirectoryManifests(expected: DirectoryManifest, actual: DirectoryManifest, request: DirectoryVerifyRequest, deletionBaseline?: DirectoryManifest): Record<string, unknown>;
|
|
43
|
+
export {};
|