mcp-ssh-server-tool 2.1.0 → 2.2.0

package/README.md

@@ -181,12 +181,60 @@ ssh_exec(command)
 }
 ```
 
+## 命令复核自动应答（auto_confirm_review）
+
+### 背景
+
+堡垒机（JumpServer）若开了**命令过滤 ACL** 且动作是「审批」，命中其命令组正则的命令会被 koko 拦下，
+在终端弹出交互提示：
+
+```
+需要复核，是否继续？[Y/N]
+```
+
+`exec` 通道没有 stdin，应答不了这个提示 —— 命令会一直卡住直到超时。
+本工具的非只读命令走的是 **PTY shell 通道**，所以**有能力把 `y` 写回去**。
+
+### 语义澄清（重要）
+
+**写 `y` 只是「提交审批申请」，命令不会立刻执行** —— 仍需审批人在 JumpServer 侧批准。
+所以本功能**不绕过任何管控**，只是把「人工在终端按 y」这一步自动化了。
+
+> ⚠️ 代价：工单的「申请人」会显示为当前堡垒机用户，但实际是工具自动发起的。
+> 审批人无法从工单上区分「本人按的」与「工具自动按的」。启用前请确认这符合你们的管控要求。
+
+### 行为
+
+| `auto_confirm_review` | 检测到复核提示时 |
+|---|---|
+| `false`（默认） | **立刻返回** `errorType: "ReviewRequired"`，不再白等到超时；`stdout` 里带上提示原文 |
+| `true` | 自动写 `y` 提交申请，然后把看门狗放宽到 `review_wait`（默认 10 分钟）等审批 |
+
+返回值里新增两个字段，便于调用方判断：
+
+- `reviewPrompted` —— 是否检测到复核提示
+- `autoConfirmed` —— 是否已自动应答
+
+**审批通过后**，shell 会继续执行原命令并回显结束哨兵 —— 也就是说
+**现有解析逻辑无需改动**，命令正常执行、`exitCode` 正常返回。
+超时未获批则返回 `errorType: "ReviewPending"`。
+
+### 开关
+
+- 每次调用传参：`auto_confirm_review: true`
+- 全局默认开启：环境变量 `SSH_AUTO_CONFIRM_REVIEW=1`
+- 等待时长：`review_wait`（秒）或环境变量 `SSH_REVIEW_WAIT_MS`（毫秒）
+
 ## 已知限制
 
 - **命令以 `exit` / `exec` 结尾会终止 shell**：哨兵无法回显，命令会走到超时。此时仍会返回已捕获的输出，但 `exitCode` 为 `null`。
 - **`exitCode` 取的是最后一条命令的退出码**：`a; b; c` 形式的复合命令，返回的是 `c` 的退出码。
 - **shell 通道有固定开销**：每次都要走一次 shell 初始化（MOTD 等），比 `exec` 慢约 1~2 秒。
 - **只读判定是安全网，不是证明**：它做静态字符串分析，绕过方式是存在的。真正的强约束应放在服务端（如堡垒机的命令过滤 ACL）。
+- **复核提示的识别靠关键词匹配**（`需要复核` / `是否继续` / `是否提交申请` / `命令需要审批`）。
+  若目标环境的提示文案不同，需同步调整 `ssh_manager.js` 里的 `REVIEW_PROMPT_RE`；
+  文案不匹配时表现为「没识别到提示，走普通超时」。
+- **自动应答只在 shell 通道生效**：只读命令走 `exec` 通道，本来也不会被拦（除非 ACL 覆盖了只读命令名）。
 
 ## 依赖
 

package/index.js

@@ -45,6 +45,18 @@ const tools = [
           enum: ['force'],
           description: '留痕控制。不传时由只读白名单自动判定：只读命令走 exec 通道（快、不产生审计记录），其余一律走 shell 通道（产生 JumpServer 可回放会话）。传 force 则强制走 shell 通道留痕。没有「关闭留痕」选项，留痕保证不可被调用方绕过。',
         },
+        auto_confirm_review: {
+          type: 'boolean',
+          description: '遇到 JumpServer「命令复核」提示（如「需要复核，是否继续？[Y/N]」）时，是否自动应答 y 以提交审批申请。默认 false（此时会立刻返回 ReviewRequired 错误，不白等超时）；也可用环境变量 SSH_AUTO_CONFIRM_REVIEW=1 设为全局默认。注意：写 y 只是提交申请，命令仍需审批人批准后才会执行 —— 不绕过任何管控。',
+        },
+        shell_timeout: {
+          type: 'number',
+          description: 'shell 通道的命令超时（秒）。默认 30，可用环境变量 SSH_SHELL_TIMEOUT_MS 覆盖。',
+        },
+        review_wait: {
+          type: 'number',
+          description: 'auto_confirm_review 生效后，等待审批人处理的时长（秒）。默认 600（10 分钟），可用环境变量 SSH_REVIEW_WAIT_MS 覆盖。',
+        },
       },
     },
   },
@@ -75,6 +87,18 @@ const tools = [
         passphrase: { type: 'string', description: '私钥密码' },
         timeout: { type: 'number', description: '超时时间（秒）', default: 10 },
         test_command: { type: 'string', description: '测试命令（默认: echo test）', default: 'echo test' },
+        auto_confirm_review: {
+          type: 'boolean',
+          description: '遇到 JumpServer「命令复核」提示时是否自动应答 y 提交审批申请。默认 false；也可用环境变量 SSH_AUTO_CONFIRM_REVIEW=1 设为全局默认。写 y 只是提交申请，命令仍需审批人批准。',
+        },
+        shell_timeout: {
+          type: 'number',
+          description: 'shell 通道的命令超时（秒）。默认 30，可用环境变量 SSH_SHELL_TIMEOUT_MS 覆盖。',
+        },
+        review_wait: {
+          type: 'number',
+          description: 'auto_confirm_review 生效后，等待审批人处理的时长（秒）。默认 600，可用环境变量 SSH_REVIEW_WAIT_MS 覆盖。',
+        },
       },
       required: ['host', 'username'],
     },
@@ -147,6 +171,14 @@ async function handleRequest(request) {
       const hasSession = toolArgs.session_id;
       const hasAuth = toolArgs.host && toolArgs.username;
 
+      // 统一整理执行选项（含「命令复核」自动应答与超时）
+      const execOpts = {
+        audit: toolArgs.audit,
+        autoConfirmReview: toolArgs.auto_confirm_review,
+        shellTimeoutMs: toolArgs.shell_timeout ? toolArgs.shell_timeout * 1000 : undefined,
+        reviewWaitMs: toolArgs.review_wait ? toolArgs.review_wait * 1000 : undefined,
+      };
+
       if (!hasSession && !hasAuth) {
         send({ jsonrpc: '2.0', id, result: { content: [{ type: 'text', text: JSON.stringify({ success: false, error: 'Either session_id or host/username required' }) }] } });
         return;
@@ -171,9 +203,9 @@ async function handleRequest(request) {
 
         let result;
         if (toolArgs.commands) {
-          result = await sshManager.execCommands(conn.sessionId, toolArgs.commands, { audit: toolArgs.audit });
+          result = await sshManager.execCommands(conn.sessionId, toolArgs.commands, execOpts);
         } else if (toolArgs.command) {
-          result = await sshManager.execCommand(conn.sessionId, toolArgs.command, { audit: toolArgs.audit });
+          result = await sshManager.execCommand(conn.sessionId, toolArgs.command, execOpts);
         }
 
         sshManager.disconnect(conn.sessionId);
@@ -184,9 +216,9 @@ async function handleRequest(request) {
       if (hasSession) {
         let result;
         if (toolArgs.commands) {
-          result = await sshManager.execCommands(toolArgs.session_id, toolArgs.commands, { audit: toolArgs.audit });
+          result = await sshManager.execCommands(toolArgs.session_id, toolArgs.commands, execOpts);
         } else if (toolArgs.command) {
-          result = await sshManager.execCommand(toolArgs.session_id, toolArgs.command, { audit: toolArgs.audit });
+          result = await sshManager.execCommand(toolArgs.session_id, toolArgs.command, execOpts);
         }
         send({ jsonrpc: '2.0', id, result: { content: [{ type: 'text', text: JSON.stringify(result) }] } });
         return;
@@ -216,7 +248,11 @@ async function handleRequest(request) {
         return;
       }
 
-      const execResult = await sshManager.execCommand(conn.sessionId, toolArgs.test_command || 'echo test');
+      const execResult = await sshManager.execCommand(conn.sessionId, toolArgs.test_command || 'echo test', {
+        autoConfirmReview: toolArgs.auto_confirm_review,
+        shellTimeoutMs: toolArgs.shell_timeout ? toolArgs.shell_timeout * 1000 : undefined,
+        reviewWaitMs: toolArgs.review_wait ? toolArgs.review_wait * 1000 : undefined,
+      });
       sshManager.disconnect(conn.sessionId);
 
       send({

package/package.json

@@ -1,33 +1,33 @@
-{
-  "name": "mcp-ssh-server-tool",
-  "version": "2.1.0",
-  "description": "MCP Server for SSH connections and remote command execution",
-  "main": "index.js",
-  "type": "module",
-  "bin": {
-    "mcp-ssh-server-tool": "bin/cli.js"
-  },
-  "scripts": {
-    "start": "node index.js"
-  },
-  "keywords": [
-    "mcp",
-    "ssh",
-    "server",
-    "mcp-server",
-    "remote-execution"
-  ],
-  "author": "",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": ""
-  },
-  "dependencies": {
-    "ssh2": "^1.15.0"
-  },
-  "engines": {
-    "node": ">=18.0.0"
-  },
-  "preferGlobal": true
-}
+{
+  "name": "mcp-ssh-server-tool",
+  "version": "2.2.0",
+  "description": "MCP Server for SSH connections and remote command execution",
+  "main": "index.js",
+  "type": "module",
+  "bin": {
+    "mcp-ssh-server-tool": "bin/cli.js"
+  },
+  "scripts": {
+    "start": "node index.js"
+  },
+  "keywords": [
+    "mcp",
+    "ssh",
+    "server",
+    "mcp-server",
+    "remote-execution"
+  ],
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": ""
+  },
+  "dependencies": {
+    "ssh2": "^1.15.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "preferGlobal": true
+}

package/ssh_manager.js

@@ -22,6 +22,30 @@ import { resolveChannel } from './readonly_policy.js';
 // 可用环境变量 SSH_SHELL_TIMEOUT_MS 覆盖
 const SHELL_TIMEOUT_MS = Number(process.env.SSH_SHELL_TIMEOUT_MS || 30000);
 
+// ---------------------------------------------------------------------------
+// JumpServer「命令复核」提示的识别与应答
+// ---------------------------------------------------------------------------
+//
+// 堡垒机开启命令过滤（ACL action=review）后，命中其命令组正则的命令会被 koko 拦下，
+// 在终端里弹出交互提示，形如：
+//
+//     需要复核，是否继续？[Y/N]
+//
+// 本工具走的是 **PTY shell 通道**，所以有能力把这个 y 写回去 —— 这就是「提交审批申请」。
+//
+// ⚠️ 语义澄清（很重要）：
+//   写 y 只是「提交申请」，命令**不会立刻执行** —— 仍需审批人在 JumpServer 侧批准。
+//   所以本功能**不绕过任何管控**，只是把「人工在终端按 y」这一步自动化了。
+//   代价：工单的「申请人」会显示为当前堡垒机用户，但实际是工具自动发起的，
+//   审批人无法从工单上区分「本人按的」与「工具自动按的」。
+//
+// 开关与时长：
+//   SSH_AUTO_CONFIRM_REVIEW=1   把「自动应答」设为全局默认（每次调用也可用参数覆盖）
+//   SSH_REVIEW_WAIT_MS          自动应答后等待审批的时长，默认 10 分钟
+const REVIEW_PROMPT_RE = /需要复核|是否继续|是否提交申请|命令需要审批/;
+const REVIEW_WAIT_MS = Number(process.env.SSH_REVIEW_WAIT_MS || 10 * 60 * 1000);
+const AUTO_CONFIRM_DEFAULT = process.env.SSH_AUTO_CONFIRM_REVIEW === '1';
+
 // 哨兵用的随机串。故意让「发送的命令行」里只出现 ${N} 而非展开值，
 // 这样 shell 回显的输入行不会与真实标记串冲突。
 const NONCE = '7f3a2c';
@@ -137,8 +161,17 @@ class SSHConnectionManager {
 
     const { channel, reason } = resolveChannel(command, options.audit);
 
+    // 未显式传参时，用环境变量决定的全局默认
+    const autoConfirmReview = options.autoConfirmReview === undefined
+      ? AUTO_CONFIRM_DEFAULT
+      : options.autoConfirmReview === true;
+
     const result = channel === 'shell'
-      ? await this._execViaShell(session, command)
+      ? await this._execViaShell(session, command, {
+          autoConfirmReview,
+          shellTimeoutMs: options.shellTimeoutMs,
+          reviewWaitMs: options.reviewWaitMs,
+        })
       : await this._execViaExec(session, command);
 
     return { ...result, channel, channelReason: reason };
@@ -183,7 +216,11 @@ class SSHConnectionManager {
   // shell 通道：非只读命令，产生可回放的 JumpServer 会话
   // ---------------------------------------------------------------------------
 
-  _execViaShell(session, command) {
+  _execViaShell(session, command, opts = {}) {
+    const autoConfirm = opts.autoConfirmReview === true;
+    const baseTimeoutMs = opts.shellTimeoutMs || SHELL_TIMEOUT_MS;
+    const reviewWaitMs = opts.reviewWaitMs || REVIEW_WAIT_MS;
+
     return new Promise((resolve) => {
       session.client.shell(
         { term: 'xterm-256color', cols: 200, rows: 50 },
@@ -195,34 +232,74 @@ class SSHConnectionManager {
 
           let buf = '';
           let settled = false;
+          let reviewPrompted = false;   // 是否检测到「命令复核」提示
+          let autoConfirmed = false;    // 是否已自动应答 y
+          let timer = null;
+
+          // 取已捕获的输出（哨兵之后的部分）
+          const partialOut = () => {
+            const k = buf.indexOf(START_MARK);
+            return k === -1 ? '' : trimBlank(stripAnsi(buf.slice(k + START_MARK.length)));
+          };
 
           const finish = (payload) => {
             if (settled) return;
             settled = true;
             clearTimeout(timer);
             try { stream.end(); } catch { /* ignore */ }
-            resolve({ ...payload, sessionId: session.sessionId, command });
+            resolve({ ...payload, sessionId: session.sessionId, command, reviewPrompted, autoConfirmed });
           };
 
-          const timer = setTimeout(() => {
-            // 超时也要交出已捕获的输出：命令可能是 exit / exec 这类
-            // 会直接终止 shell 的，哨兵永远不会出现
-            const k = buf.indexOf(START_MARK);
-            const partial = k === -1
-              ? ''
-              : trimBlank(stripAnsi(buf.slice(k + START_MARK.length)));
+          // 可重置的看门狗：超时也要交出已捕获的输出，
+          // 因为命令可能是 exit / exec 这类会直接终止 shell 的，哨兵永远不会出现
+          const armTimer = (ms, onTimeout) => {
+            clearTimeout(timer);
+            timer = setTimeout(onTimeout, ms);
+          };
+
+          armTimer(baseTimeoutMs, () => {
             finish({
               success: false,
-              error: `命令超时（${SHELL_TIMEOUT_MS}ms）。会话已在 JumpServer 留痕`,
+              error: `命令超时（${baseTimeoutMs}ms）。会话已在 JumpServer 留痕`,
               errorType: 'Timeout',
-              stdout: partial,
+              stdout: partialOut(),
               exitCode: null,
             });
-          }, SHELL_TIMEOUT_MS);
+          });
 
           stream.on('data', (d) => {
             buf += d.toString();
 
+            // ---- JumpServer「命令复核」拦截 ----
+            if (!reviewPrompted && REVIEW_PROMPT_RE.test(stripAnsi(buf))) {
+              reviewPrompted = true;
+
+              if (!autoConfirm) {
+                // 不自动应答：立刻给出明确错误，别让调用方白等到超时
+                finish({
+                  success: false,
+                  error: '命令被 JumpServer「命令复核」拦截：需在终端按 y 提交审批申请（本次未自动应答）',
+                  errorType: 'ReviewRequired',
+                  stdout: partialOut(),
+                  exitCode: null,
+                });
+                return;
+              }
+
+              // 自动应答：写 y 提交审批申请，并把看门狗放宽到 reviewWaitMs
+              try { stream.write('y\n'); } catch { /* ignore */ }
+              autoConfirmed = true;
+              armTimer(reviewWaitMs, () => {
+                finish({
+                  success: false,
+                  error: `已提交审批申请，但等待 ${Math.round(reviewWaitMs / 1000)}s 仍未获批。会话已在 JumpServer 留痕`,
+                  errorType: 'ReviewPending',
+                  stdout: partialOut(),
+                  exitCode: null,
+                });
+              });
+            }
+
             const i = buf.indexOf(START_MARK);
             if (i === -1) return;
             const j = buf.indexOf(END_MARK, i + START_MARK.length);
@@ -241,7 +318,9 @@ class SSHConnectionManager {
               // pty 下 stderr 与 stdout 合并，内容都在 stdout 里
               stderr: '',
               exitCode: parseInt(m[1], 10),
-              note: '该会话已由 JumpServer 录像，可在控制台回放',
+              note: autoConfirmed
+                ? '命令经审批后执行；该会话已由 JumpServer 录像，可在控制台回放'
+                : '该会话已由 JumpServer 录像，可在控制台回放',
             });
           });