@pyrokine/mcp-ssh 1.3.0 → 2.0.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 CHANGED
@@ -14,7 +14,7 @@ A comprehensive SSH MCP Server for AI assistants (Claude, Cursor, Windsurf, etc.
14
14
 
15
15
  ## Features
16
16
 
17
- - **Multiple Authentication**: Password, SSH key, SSH agent
17
+ - **Multiple Authentication**: Password, SSH key
18
18
  - **SSH Config Support**: Read `~/.ssh/config` with Host aliases, `Host *` inheritance, ProxyJump (`user@host:port`)
19
19
  - **Connection Management**: Connection pooling, keepalive, auto-reconnect
20
20
  - **Session Persistence**: Sessions info saved for reconnection
@@ -315,8 +315,8 @@ ssh_sync(..., dryRun=true)
315
315
 
316
316
  If rsync is not available on remote or local, it automatically falls back to SFTP.
317
317
 
318
- **Note**: rsync mode uses SSH key/agent authentication and disables strict host key checking (
319
- `StrictHostKeyChecking=no`) for convenience. If you require host key verification, use SFTP mode instead.
318
+ **Note**: rsync mode uses SSH key/agent authentication and sets `StrictHostKeyChecking=accept-new`.
319
+ If you require strict host key verification and management, use SFTP mode instead.
320
320
 
321
321
  ### Persistent PTY Sessions (top, tmux, etc.)
322
322
 
@@ -405,6 +405,56 @@ ssh_forward_close(forwardId="fwd_1_xxx")
405
405
  | `env` | object | - | Additional environment variables |
406
406
  | `pty` | boolean | false | Enable PTY mode for interactive commands |
407
407
 
408
+ ## Security
409
+
410
+ ### Path Whitelist for Key/Config Files
411
+
412
+ `keyPath` (private key) and `configPath` (SSH config) must reside under one of the following directories:
413
+
414
+ - `~/.ssh/` — user SSH directory
415
+ - `/etc/ssh/` — system-wide SSH directory
416
+
417
+ To allow additional directories, set the `SSH_MCP_ALLOWED_KEY_DIRS` environment variable, separated by `:` on
418
+ Linux/macOS or `;` on Windows:
419
+
420
+ ```bash
421
+ export SSH_MCP_ALLOWED_KEY_DIRS=/opt/secrets:/var/lib/keys
422
+ ```
423
+
424
+ Files outside the whitelist are rejected with `Invalid private key path: ...` or `Invalid config path: ...`.
425
+
426
+ ### Optional File-Ops Path Whitelist
427
+
428
+ `ssh_upload`, `ssh_download`, `ssh_sync` accept arbitrary local paths by default. To restrict them to specific
429
+ directories (recommended for shared environments), set `SSH_MCP_FILE_OPS_ALLOW_DIRS` (paths separated by Node's
430
+ `path.delimiter` — `:` on POSIX, `;` on Windows):
431
+
432
+ ```bash
433
+ export SSH_MCP_FILE_OPS_ALLOW_DIRS=/tmp:/home/me/work
434
+ ```
435
+
436
+ When set, any local path outside the whitelist is rejected. Symlinks are resolved via `realpath` to prevent escape.
437
+ When unset, no restriction is applied (preserves flexibility).
438
+
439
+ ### File Size Limits
440
+
441
+ - Private key files: max 64 KB
442
+ - SSH config files: max 1 MB
443
+
444
+ Files exceeding these limits are rejected before being read.
445
+
446
+ ### Symlink Handling in `ssh_sync`
447
+
448
+ `ssh_sync(direction="upload", ...)` handles local symlinks differently depending on the underlying transport:
449
+
450
+ | `followSymlinks` | SFTP path | rsync path |
451
+ |-------------------|------------------------------------------------------------|-----------------------------------------------------------------------------|
452
+ | `false` (default) | Skipped, returned in `skippedSymlinks`, printed as warning | Copied as-is (rsync default: preserves the symlink without dereferencing) |
453
+ | `true` | Followed: link target contents are uploaded | Followed via rsync `-L` / `--copy-links`: link target contents are uploaded |
454
+
455
+ Both default modes are safe (neither uploads link target contents). The divergence is whether the destination keeps the
456
+ symlink: SFTP omits it entirely, rsync preserves it as a symlink.
457
+
408
458
  ## Project Structure
409
459
 
410
460
  ```
package/README_zh.md CHANGED
@@ -14,7 +14,7 @@
14
14
 
15
15
  ## 功能特性
16
16
 
17
- - **多种认证方式**:密码、SSH 密钥、SSH Agent
17
+ - **多种认证方式**:密码、SSH 密钥
18
18
  - **SSH Config 支持**:读取 `~/.ssh/config`,支持 Host 多别名、`Host *` 继承、ProxyJump(`user@host:port` 格式)
19
19
  - **连接管理**:连接池复用、心跳保持、自动重连
20
20
  - **会话持久化**:会话信息保存,支持重连
@@ -229,8 +229,8 @@ ssh_connect(
229
229
  // 输出: appuser
230
230
  ```
231
231
 
232
- 默认加载 shell 配置以确保环境变量可用(`su -c` 创建非交互式 shell,不会自动执行 rc 文件)。支持 bash(`.bashrc`)、zsh(`.zshrc`
233
- )及其他 shell(`.profile`)。如不需要可设置 `loadProfile=false`。
232
+ 默认加载 shell 配置以确保环境变量可用(`su -c` 创建非交互式 shell,不会自动执行 rc 文件),支持 bash(`.bashrc`)、zsh(`.zshrc`
233
+ )及其他 shell(`.profile`),如不需要可设置 `loadProfile=false`
234
234
 
235
235
  ### 交互式命令(PTY 模式)
236
236
 
@@ -312,10 +312,10 @@ ssh_sync(
312
312
  ssh_sync(..., dryRun=true)
313
313
  ```
314
314
 
315
- 如果远程或本地没有 rsync,会自动回退到 SFTP。
315
+ 如果远程或本地没有 rsync,会自动回退到 SFTP
316
316
 
317
- **注意**:rsync 模式使用 SSH 密钥/代理认证,并禁用严格主机密钥检查(`StrictHostKeyChecking=no`)以方便使用。如需主机密钥验证,请使用
318
- SFTP 模式。
317
+ **注意**:rsync 模式使用 SSH 密钥/代理认证,并设置 `StrictHostKeyChecking=accept-new`(首次连接会自动接受主机密钥),
318
+ 如需严格的主机密钥验证与管理,请使用 SFTP 模式
319
319
 
320
320
  ### 持久化 PTY 会话(top、tmux 等)
321
321
 
@@ -404,6 +404,52 @@ ssh_forward_close(forwardId="fwd_1_xxx")
404
404
  | `env` | object | - | 额外环境变量 |
405
405
  | `pty` | boolean | false | 启用 PTY 模式(用于交互式命令) |
406
406
 
407
+ ## 安全
408
+
409
+ ### 私钥/配置文件路径白名单
410
+
411
+ `keyPath`(私钥)和 `configPath`(SSH 配置文件)必须位于以下目录之一:
412
+
413
+ - `~/.ssh/` — 用户 SSH 目录
414
+ - `/etc/ssh/` — 系统 SSH 目录
415
+
416
+ 如需扩展白名单,设置环境变量 `SSH_MCP_ALLOWED_KEY_DIRS`,Linux/macOS 用 `:` 分隔,Windows 用 `;` 分隔:
417
+
418
+ ```bash
419
+ export SSH_MCP_ALLOWED_KEY_DIRS=/opt/secrets:/var/lib/keys
420
+ ```
421
+
422
+ 白名单外的文件会被拒绝,错误信息为 `Invalid private key path: ...` 或 `Invalid config path: ...`
423
+
424
+ ### 可选:文件操作路径白名单
425
+
426
+ `ssh_upload`、`ssh_download`、`ssh_sync` 默认接受任意本地路径,如需在共享环境下限定到指定目录(推荐),
427
+ 设置 `SSH_MCP_FILE_OPS_ALLOW_DIRS`(路径分隔符跟随 Node `path.delimiter`:POSIX 用 `:`,Windows 用 `;`):
428
+
429
+ ```bash
430
+ export SSH_MCP_FILE_OPS_ALLOW_DIRS=/tmp:/home/me/work
431
+ ```
432
+
433
+ 设置后,白名单外的本地路径会被拒绝,symlink 会通过 `realpath` 解析以防逃逸;未设置时不做限制(保留灵活性)
434
+
435
+ ### 文件大小上限
436
+
437
+ - 私钥文件:最大 64 KB
438
+ - SSH 配置文件:最大 1 MB
439
+
440
+ 超过上限的文件在读取前即被拒绝
441
+
442
+ ### `ssh_sync` 的 symlink 处理
443
+
444
+ `ssh_sync(direction="upload", ...)` 对本地 symlink 的处理因底层传输方式而异:
445
+
446
+ | `followSymlinks` | SFTP 路径 | rsync 路径 |
447
+ |------------------|----------------------------------------|--------------------------------------------|
448
+ | `false`(默认) | 跳过,写入 `skippedSymlinks` 字段,warning 中提示 | 按 symlink 本身复制(rsync 默认:保留链接,不上传目标内容) |
449
+ | `true` | 跟随:上传链接目标内容 | 通过 rsync `-L` / `--copy-links` 跟随:上传链接目标内容 |
450
+
451
+ 两个默认模式都安全(都不会上传链接目标内容),差异仅在于目标端是否保留 symlink:SFTP 完全跳过不传,rsync 保留为 symlink
452
+
407
453
  ## 项目结构
408
454
 
409
455
  ```
@@ -421,11 +467,11 @@ mcp-ssh/
421
467
 
422
468
  ## 贡献
423
469
 
424
- 欢迎贡献!请随时提交 Pull Request。
470
+ 欢迎贡献!请随时提交 Pull Request
425
471
 
426
472
  ## 许可证
427
473
 
428
- MIT 许可证 - 详见 [LICENSE](LICENSE)。
474
+ MIT 许可证 - 详见 [LICENSE](LICENSE)
429
475
 
430
476
  ## 相关项目
431
477
 
@@ -1,18 +1,21 @@
1
1
  /**
2
2
  * SSH File Operations - 文件操作
3
3
  */
4
+ import { SFTPWrapper } from 'ssh2';
4
5
  import { FileInfo, TransferProgress } from './types.js';
6
+ /** 由 SessionManager.disconnect 调用,防止 alias 重连后读到旧主机的判断 */
7
+ export declare function clearRsyncCache(alias?: string): void;
5
8
  /**
6
9
  * 上传文件
7
10
  */
8
- export declare function uploadFile(alias: string, localPath: string, remotePath: string, onProgress?: (progress: TransferProgress) => void): Promise<{
11
+ export declare function uploadFile(alias: string, localPath: string, remotePath: string, onProgress?: (progress: TransferProgress) => void, sharedSftp?: SFTPWrapper): Promise<{
9
12
  success: boolean;
10
13
  size: number;
11
14
  }>;
12
15
  /**
13
16
  * 下载文件
14
17
  */
15
- export declare function downloadFile(alias: string, remotePath: string, localPath: string, onProgress?: (progress: TransferProgress) => void): Promise<{
18
+ export declare function downloadFile(alias: string, remotePath: string, localPath: string, onProgress?: (progress: TransferProgress) => void, sharedSftp?: SFTPWrapper): Promise<{
16
19
  success: boolean;
17
20
  size: number;
18
21
  }>;
@@ -34,7 +37,7 @@ export declare function writeFile(alias: string, remotePath: string, content: st
34
37
  /**
35
38
  * 列出目录内容
36
39
  */
37
- export declare function listDir(alias: string, remotePath: string, showHidden?: boolean): Promise<FileInfo[]>;
40
+ export declare function listDir(alias: string, remotePath: string, showHidden?: boolean, sharedSftp?: SFTPWrapper): Promise<FileInfo[]>;
38
41
  /**
39
42
  * 获取文件信息
40
43
  */
@@ -61,6 +64,7 @@ export declare function syncFiles(alias: string, localPath: string, remotePath:
61
64
  dryRun?: boolean;
62
65
  exclude?: string[];
63
66
  recursive?: boolean;
67
+ followSymlinks?: boolean;
64
68
  }): Promise<SyncResult>;
65
69
  /**
66
70
  * 使用 SFTP 同步文件
@@ -70,6 +74,7 @@ type SyncResult = {
70
74
  method: 'rsync' | 'sftp';
71
75
  filesTransferred?: number;
72
76
  bytesTransferred?: number;
77
+ skippedSymlinks?: number;
73
78
  output?: string;
74
79
  };
75
80
  export {};