mcp-ssh-server-tool 2.0.1 → 2.1.0

package/README.md

@@ -8,6 +8,7 @@
 - 🔑 **公钥认证** - 使用私钥文件连接到 SSH 服务器
 - 💻 **远程命令执行** - 在连接的服务器上执行命令并获取输出
 - 📊 **会话管理** - 管理多个 SSH 连接会话
+- 🛡️ **按需留痕** - 只读命令走轻量通道，变更命令走可审计通道（见下）
 
 ## 安装
 
@@ -34,13 +35,18 @@ npx -y mcp-ssh-server-tool
 在 SSH 会话中执行命令
 
 **参数：**
-- `session_id`: SSH 会话 ID (必需)
-- `command`: 要执行的命令 (必需)
+- `host` / `username` / `password` 等：单次执行时传入，自动连接→执行→断开
+- `session_id`: 会话 ID（连续执行多命令时使用，先调 `ssh_connect` 获取）
+- `command`: 要执行的命令（单条）
+- `commands`: 命令数组（按顺序执行）
+- `audit`: 留痕控制，取值 `"force"`（可选，见下节）
 
 **返回：**
 - `stdout`: 标准输出
 - `stderr`: 标准错误
 - `exitCode`: 退出码
+- `channel`: 实际使用的通道（`exec` | `shell`）
+- `channelReason`: 选择该通道的原因
 
 ### ssh_disconnect
 断开 SSH 连接
@@ -51,6 +57,77 @@ npx -y mcp-ssh-server-tool
 ### ssh_list_sessions
 列出所有活动的 SSH 会话
 
+## 按需留痕（audit）
+
+### 背景
+
+在堡垒机（JumpServer / KoKo 等）场景下，SSH 通道类型决定了会话是否被录像：
+
+| SSH 通道 | 堡垒机归类 | 是否录像 |
+|---|---|---|
+| `exec`（`client.exec()`） | 命令执行 | ❌ 不支持录像 |
+| `shell`（`client.shell()`） | 正常会话 | ✅ 完整录像 |
+
+> 注意：是否分配 PTY **不影响**这个判定。`exec` 即使带 `pty: true`，仍归为「命令执行」、不录像。
+
+这意味着：如果所有命令都走 `exec`，变更操作在堡垒机侧**没有操作级审计**；如果都走 `shell`，日常只读巡检又会灌满审计记录。
+
+### 行为
+
+`ssh_exec` 会按命令性质自动选择通道：
+
+```
+ssh_exec(command)
+  ├─ audit === 'force'   → shell 通道（强制留痕）
+  ├─ 命中只读白名单       → exec 通道（不留痕，快且输出干净）
+  └─ 其余一律            → shell 通道（留痕）
+```
+
+**默认留痕，且不提供「关闭留痕」的选项。**
+
+这样判错的失败方向是单向的：
+
+- 只读命令被误判为需留痕 → 多一条审计记录（无害）
+- 变更命令被误判为只读 → 静默执行且不留痕（**最坏情况，已在设计上避免**）
+
+### 只读判定
+
+判定逻辑在 `readonly_policy.js`，采用「默认拒绝 + 显式约束」：
+
+- 不在白名单里的命令 → 一律留痕
+- 能读也能写的命令（`ip` / `docker` / `kubectl` / `find` / `sed` …）必须显式约束写形态
+- 无法静态分析的形态（`>` 重定向、`$(...)` 命令替换、管道进 shell）直接否决
+- 语义级写操作由 `denyPattern` 拦截（如 `awk` 的 `system()`、`sysctl` 的 `key=value`、`mysql` 的 `INTO OUTFILE`）
+
+可通过 `loadPolicy(jsonPath)` 传入 JSON 覆盖内置白名单：
+
+```json
+{
+  "ls": {},
+  "tail":      { "denyArgs": ["-f", "--follow"] },
+  "sed":       { "denyArgs": ["-i", "--in-place"] },
+  "systemctl": { "sub": ["status", "is-active", "list-units"] },
+  "mysql":     { "requirePattern": "\\b(SELECT|SHOW)\\b" }
+}
+```
+
+字段说明：
+
+| 字段 | 含义 |
+|---|---|
+| `sub` | 允许出现的子命令/位置参数，命中任一即通过；省略 = 不限制 |
+| `denyArgs` | 禁止出现的参数，命中任一即否决 |
+| `denyPattern` | 正则，匹配到即否决（语义级写操作） |
+| `requirePattern` | 正则，必须匹配才通过（如 SQL 必须是查询语句） |
+
+键名规则：命令名中的 `-` 换成 `_`（如 `redis-cli` → `redis_cli`）。
+
+### 环境变量
+
+| 变量 | 默认 | 说明 |
+|---|---|---|
+| `SSH_SHELL_TIMEOUT_MS` | `30000` | shell 通道单条命令的超时上限（毫秒） |
+
 ## 使用示例
 
 ### 1. 密码认证连接
@@ -86,7 +163,17 @@ npx -y mcp-ssh-server-tool
 }
 ```
 
-### 4. 断开连接
+### 4. 强制留痕执行（变更操作）
+
+```json
+{
+  "session_id": "<session_id>",
+  "command": "systemctl restart nginx",
+  "audit": "force"
+}
+```
+
+### 5. 断开连接
 
 ```json
 {
@@ -94,11 +181,17 @@ npx -y mcp-ssh-server-tool
 }
 ```
 
+## 已知限制
+
+- **命令以 `exit` / `exec` 结尾会终止 shell**：哨兵无法回显，命令会走到超时。此时仍会返回已捕获的输出，但 `exitCode` 为 `null`。
+- **`exitCode` 取的是最后一条命令的退出码**：`a; b; c` 形式的复合命令，返回的是 `c` 的退出码。
+- **shell 通道有固定开销**：每次都要走一次 shell 初始化（MOTD 等），比 `exec` 慢约 1~2 秒。
+- **只读判定是安全网，不是证明**：它做静态字符串分析，绕过方式是存在的。真正的强约束应放在服务端（如堡垒机的命令过滤 ACL）。
+
 ## 依赖
 
 - Node.js >= 18.0.0
 - ssh2 >= 1.15.0
-- uuid >= 9.0.0
 
 ## License
 

package/index.js

@@ -40,6 +40,11 @@ const tools = [
         session_id: { type: 'string', description: '会话 ID（连续执行多命令时使用，先调用 ssh_connect 获取）' },
         command: { type: 'string', description: '要执行的命令（单个命令）' },
         commands: { type: 'array', items: { type: 'string' }, description: '要执行的命令列表（多个命令按顺序执行）' },
+        audit: {
+          type: 'string',
+          enum: ['force'],
+          description: '留痕控制。不传时由只读白名单自动判定：只读命令走 exec 通道（快、不产生审计记录），其余一律走 shell 通道（产生 JumpServer 可回放会话）。传 force 则强制走 shell 通道留痕。没有「关闭留痕」选项，留痕保证不可被调用方绕过。',
+        },
       },
     },
   },
@@ -166,9 +171,9 @@ async function handleRequest(request) {
 
         let result;
         if (toolArgs.commands) {
-          result = await sshManager.execCommands(conn.sessionId, toolArgs.commands);
+          result = await sshManager.execCommands(conn.sessionId, toolArgs.commands, { audit: toolArgs.audit });
         } else if (toolArgs.command) {
-          result = await sshManager.execCommand(conn.sessionId, toolArgs.command);
+          result = await sshManager.execCommand(conn.sessionId, toolArgs.command, { audit: toolArgs.audit });
         }
 
         sshManager.disconnect(conn.sessionId);
@@ -179,9 +184,9 @@ async function handleRequest(request) {
       if (hasSession) {
         let result;
         if (toolArgs.commands) {
-          result = await sshManager.execCommands(toolArgs.session_id, toolArgs.commands);
+          result = await sshManager.execCommands(toolArgs.session_id, toolArgs.commands, { audit: toolArgs.audit });
         } else if (toolArgs.command) {
-          result = await sshManager.execCommand(toolArgs.session_id, toolArgs.command);
+          result = await sshManager.execCommand(toolArgs.session_id, toolArgs.command, { audit: toolArgs.audit });
         }
         send({ jsonrpc: '2.0', id, result: { content: [{ type: 'text', text: JSON.stringify(result) }] } });
         return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-ssh-server-tool",
-  "version": "2.0.1",
+  "version": "2.1.0",
   "description": "MCP Server for SSH connections and remote command execution",
   "main": "index.js",
   "type": "module",
@@ -10,7 +10,13 @@
   "scripts": {
     "start": "node index.js"
   },
-  "keywords": ["mcp", "ssh", "server", "mcp-server", "remote-execution"],
+  "keywords": [
+    "mcp",
+    "ssh",
+    "server",
+    "mcp-server",
+    "remote-execution"
+  ],
   "author": "",
   "license": "MIT",
   "repository": {

package/readonly_policy.js

@@ -0,0 +1,297 @@
+/**
+ * readonly_policy.js —— 只读命令判定（默认拒绝）
+ *
+ * 用途：决定一条命令走哪条 SSH 通道
+ *   命中只读白名单 → exec 通道（快、干净、不产生审计记录）
+ *   其余一律       → shell 通道（koko 归为 normal 会话，完整录像）
+ *
+ * ⚠️ 本模块是「安全网」，不是「证明」。
+ * 判错的代价是单向的：把写命令误判为只读 → 它会被自动执行且不留痕（最坏情况）。
+ * 因此设计上取保守策略：
+ *   1. 默认拒绝 —— 不在白名单里的一律留痕
+ *   2. 能读也能写的命令（ip / docker / kubectl / find / sed …）必须显式约束
+ *   3. 无法静态分析的形态（重定向、命令替换、管道进 shell）直接否决
+ *   4. 有 `denyPattern` 用于拦截语义级写操作（awk 的 system()、sysctl 的 key=value）
+ *
+ * 真正的强约束在服务端：JumpServer 的命令过滤 ACL（acls_command_filter_acls）。
+ * 本模块只负责「该不该留痕」，不负责「能不能执行」。
+ */
+
+import fs from 'fs';
+
+// 无参数约束的纯查看命令（不改变任何系统状态）
+const PURE_READ = {
+  ls: 1, ll: 1, dir: 1, vdir: 1, pwd: 1, cat: 1, head: 1, tac: 1, nl: 1, wc: 1,
+  stat: 1, file: 1, du: 1, df: 1, tree: 1, which: 1, whereis: 1, type: 1,
+  readlink: 1, realpath: 1, basename: 1, dirname: 1, locate: 1,
+  md5sum: 1, sha1sum: 1, sha256sum: 1, cksum: 1, cmp: 1, diff: 1, comm: 1,
+  strings: 1, xxd: 1, od: 1, hexdump: 1,
+  grep: 1, egrep: 1, fgrep: 1, rg: 1, zgrep: 1, zcat: 1, zless: 1,
+  cut: 1, sort: 1, uniq: 1, tr: 1, column: 1, paste: 1, join: 1, fold: 1,
+  expand: 1, rev: 1, jq: 1, yq: 1,
+  uname: 1, hostname: 1, arch: 1, nproc: 1, getconf: 1, uptime: 1, date: 1, cal: 1,
+  lscpu: 1, lsblk: 1, lspci: 1, lsusb: 1, lsmod: 1, modinfo: 1,
+  free: 1, vmstat: 1, mpstat: 1, iostat: 1, sar: 1, pidstat: 1,
+  ps: 1, pstree: 1, pidof: 1, pgrep: 1, lsof: 1,
+  w: 1, who: 1, whoami: 1, id: 1, groups: 1, users: 1, last: 1, lastlog: 1, lastb: 1,
+  runlevel: 1, ausearch: 1, aureport: 1, findmnt: 1,
+  lvs: 1, vgs: 1, pvs: 1, lvdisplay: 1, vgdisplay: 1, pvdisplay: 1,
+  xfs_info: 1, dumpe2fs: 1, quota: 1,
+  netstat: 1, ss: 1, dig: 1, nslookup: 1, host: 1, getent: 1,
+  getfacl: 1, lsattr: 1, systemd_analyze: 1, atq: 1,
+  env: 1, printenv: 1, echo: 1, printf: 1, history: 1,
+  ping: 1, ping6: 1, traceroute: 1, tracepath: 1, mtr: 1,
+  iptables_save: 1, ip6tables_save: 1,
+};
+
+// 需要约束的命令
+const CONSTRAINED = {
+  // --- 可读可写，必须挡住写形态 ---
+  tail: { denyArgs: ['-f', '--follow', '-F', '--follow=name'] },
+  find: { denyArgs: ['-delete', '-exec', '-execdir', '-ok', '-okdir', '-fprint', '-fprint0', '-fprintf', '-fls'] },
+  sed: { denyArgs: ['-i', '--in-place'], denyPattern: /\bw\s+\S/ },
+  awk: { denyPattern: /system\s*\(|\|\s*["']?\s*(sh|bash)\b|print(f)?\s*>>?\s*["']?\// },
+  sort: { denyArgs: ['-o', '--output'] },
+
+  // --- 磁盘 / 文件系统：只放行明确的只读形态 ---
+  fdisk: { sub: ['-l', '--list'] },
+  sfdisk: { sub: ['-l', '--list', '-d', '--dump'] },
+  gdisk: { sub: ['-l', '--list'] },
+  parted: { sub: ['print', '-l', '--list'] },
+  blkid: { denyArgs: ['-g', '--garbage-collect'] },
+  smartctl: { denyArgs: ['-t', '--test', '-s', '--set', '-o', '--offlineauto'] },
+  tune2fs: { sub: ['-l'] },
+  e2fsck: { sub: ['-n'] },
+  // mount 已移除：无参数时是查看，带参数就是挂载，无法静态区分。
+  // 查看挂载请用 findmnt 或 cat /proc/mounts。
+
+  // --- 内核参数：sysctl -w 与 key=value 两种写法都要挡 ---
+  sysctl: { denyArgs: ['-w', '--write', '-p', '--load'], denyPattern: /[A-Za-z0-9_.]+\s*=/ },
+
+  // --- dmesg：-c/-C 会清空环形缓冲区 ---
+  dmesg: { denyArgs: ['-c', '-C', '--read-clear', '--clear', '-D', '--delete'] },
+
+  // --- 网络：这些命令读和写的子命令长得很像 ---
+  ip: {
+    sub: ['addr', 'a', 'link', 'route', 'r', 'neigh', 'n', '-s', '-d', 'maddr', 'rule'],
+    denyArgs: ['set', 'add', 'del', 'delete', 'change', 'replace', 'append', 'flush', 'up', 'down'],
+  },
+  ifconfig: {
+    denyArgs: ['up', 'down', 'mtu', 'promisc', '-promisc', 'arp', '-arp', 'add', 'del', 'netmask', 'broadcast', 'txqueuelen'],
+    denyPattern: /\b\d{1,3}(\.\d{1,3}){3}\b/,
+  },
+  route: { denyArgs: ['add', 'del', 'delete', 'change', 'replace', 'flush'] },
+  arp: { denyArgs: ['-d', '-s', '--delete', '--set', '-f', '--file'] },
+  ethtool: {
+    denyArgs: ['-s', '--change', '-A', '--pause', '-G', '--set-ring', '-K', '--features',
+               '-L', '--set-channels', '-N', '--set-ntuple', '-W', '--set-dump', '-E', '--eeprom', '-p', '--blink'],
+  },
+  conntrack: { denyArgs: ['-F', '-D', '-I', '-U', '--flush', '--delete', '--create', '--update'] },
+  nc: { denyArgs: ['-l', '-e', '-c', '--listen', '--exec'] },
+  nmcli: {
+    sub: ['device', 'connection', 'general', 'networking', 'radio', 'monitor', 'status', 'show'],
+    denyArgs: ['up', 'down', 'modify', 'add', 'delete', 'connect', 'disconnect', 'reload',
+               'on', 'off', 'create', 'remove', 'set', 'import'],
+  },
+  firewall_cmd: {
+    sub: ['--list-all', '--list-all-zones', '--state', '--list-ports', '--list-services',
+          '--list-zones', '--get-zones', '--get-default-zone', '--list-rich-rules',
+          '--list-icmp-blocks', '--list-interfaces', '--query-panic'],
+  },
+  iptables: {
+    sub: ['-L', '--list', '-S', '--list-rules'],
+    denyArgs: ['-A', '-I', '-D', '-F', '-N', '-X', '-P', '-Z', '-E', '-R', '-C'],
+  },
+  nft: { sub: ['list'] },
+
+  // --- 服务与日志 ---
+  systemctl: {
+    sub: ['status', 'is-active', 'is-enabled', 'is-failed', 'list-units', 'list-unit-files',
+          'show', 'cat', 'list-dependencies', 'list-timers', 'list-jobs', 'list-sockets',
+          '--version', '--failed', 'get-default'],
+  },
+  service: { sub: ['status'] },
+  chkconfig: { sub: ['--list'] },
+  journalctl: { denyArgs: ['-f', '--follow', '--vacuum-time', '--vacuum-size', '--vacuum-files', '--rotate', '--flush'] },
+
+  // --- 进程 ---
+  fuser: { denyArgs: ['-k', '--kill'] },
+
+  // --- 包管理：只放行清单/查询类子命令 ---
+  rpm: { sub: ['-qa', '-q', '-qi', '-ql', '-qf', '-qc', '-qd', '-qR', '-V', '--verify'] },
+  yum: { sub: ['list', 'info', 'repolist', 'check-update'], denyArgs: ['undo', 'rollback', 'redo', 'install', 'remove', 'erase', 'update', 'upgrade', 'autoremove', 'clean', 'mark', 'group'] },
+  dnf: { sub: ['list', 'info', 'repolist', 'check-update', 'history'], denyArgs: ['undo', 'rollback', 'redo', 'install', 'remove', 'erase', 'update', 'upgrade', 'autoremove', 'clean', 'mark', 'group'] },
+  apt: { sub: ['list', 'show', 'search'] },
+  apt_cache: { sub: ['policy', 'show', 'search'] },
+  dpkg: { sub: ['-l', '-s', '-L', '--get-selections', '-l'] },
+  zypper: { sub: ['search', 'info', 'list-updates', 'packages'] },
+  pacman: { sub: ['-Q', '-Qi', '-Ql', '-Qs', '-Qe'] },
+
+  // --- 容器 / K8s ---
+  docker: {
+    sub: ['ps', 'images', 'logs', 'inspect', 'stats', 'version', 'info', 'top', 'port',
+          'diff', 'network', 'volume', 'system', 'image', 'container', 'events', 'history'],
+    denyArgs: ['run', 'create', 'rm', 'rmi', 'start', 'stop', 'restart', 'kill', 'exec',
+               'build', 'push', 'pull', 'prune', 'pause', 'unpause', 'update', 'commit',
+               'tag', 'login', 'logout', 'import', 'load', 'save', 'swarm', 'stack',
+               'plugin', 'attach', 'cp', 'rename', 'wait'],
+  },
+  podman: {
+    sub: ['ps', 'images', 'logs', 'inspect', 'version', 'info', 'top', 'stats'],
+    denyArgs: ['run', 'create', 'rm', 'rmi', 'start', 'stop', 'restart', 'kill', 'exec',
+               'build', 'push', 'pull', 'prune', 'pause', 'unpause', 'commit', 'tag', 'cp'],
+  },
+  crictl: {
+    sub: ['ps', 'pods', 'images', 'inspect', 'logs', 'stats', 'version', 'info'],
+    denyArgs: ['rm', 'rmi', 'stop', 'start', 'run', 'create', 'pull', 'update', 'exec'],
+  },
+  ctr: {
+    sub: ['c', 'n', 's', 'i'],
+    denyArgs: ['rm', 'remove', 'pull', 'push', 'create', 'run', 'start', 'stop', 'kill', 'delete'],
+  },
+  kubectl: {
+    sub: ['get', 'describe', 'logs', 'top', 'version', 'config', 'explain',
+          'cluster-info', 'api-resources', 'auth', 'events'],
+    denyArgs: ['set', 'unset', 'delete', 'apply', 'create', 'edit', 'patch', 'replace',
+               'scale', 'rollout', 'exec', 'port-forward', 'drain', 'cordon', 'uncordon',
+               'label', 'annotate', 'cp', 'taint', 'run', 'expose', 'attach', 'debug',
+               'set-context', 'set-cluster', 'set-credentials', 'use-context',
+               'rename-context', 'delete-context', 'delete-cluster', 'delete-user'],
+  },
+  helm: {
+    sub: ['list', 'status', 'get', 'history', 'template', 'show', 'search', 'version', 'env'],
+    denyArgs: ['install', 'upgrade', 'uninstall', 'rollback', 'repo', 'plugin', 'pull', 'push', 'package', 'dependency'],
+  },
+
+  // --- 中间件：靠 requirePattern 限定为查询语句 ---
+  mysql: {
+    requirePattern: /\b(SELECT|SHOW|DESC|DESCRIBE|EXPLAIN)\b/i,
+    denyPattern: /INTO\s+(OUTFILE|DUMPFILE)/i,
+  },
+  mysqladmin: { sub: ['status', 'processlist', 'version', 'variables', 'ping'] },
+  psql: {
+    requirePattern: /\b(SELECT|SHOW|TABLE|EXPLAIN)\b/i,
+    denyPattern: /INTO\s+(OUTFILE|DUMPFILE)|\bCOPY\b[\s\S]*\bTO\b/i,
+  },
+  mongosh: {
+    requirePattern: /\b(db\.stats|db\.\S+\.(find|findOne|count|aggregate)|show\s+(dbs|collections|tables))\b/i,
+  },
+  redis_cli: {
+    requirePattern: /\b(GET|MGET|INFO|TTL|PTTL|SCAN|KEYS|DBSIZE|LLEN|LRANGE|HGET|HGETALL|SMEMBERS|SISMEMBER|ZRANGE|ZCARD|TYPE|EXISTS|STRLEN|MEMORY|CLIENT\s+LIST|SLOWLOG\s+GET|--scan)\b/i,
+  },
+  rabbitmqctl: { sub: ['list_queues', 'status', 'list_connections', 'list_exchanges', 'list_channels', 'list_nodes', 'list_vhosts', 'environment'] },
+  kafka_topics: { sub: ['--list', '--describe'] },
+  kafka_consumer_groups: { sub: ['--list', '--describe'] },
+  nginx: { sub: ['-t', '-T', '-v', '-V'] },
+  apachectl: { sub: ['-t', '-S', '-M', '-v'] },
+  httpd: { sub: ['-t', '-S', '-M', '-v'] },
+  haproxy: { sub: ['-c', '-v', '-vv'] },
+
+  // --- 计划任务 / 权限 / 变量 ---
+  crontab: { sub: ['-l'] },
+  at: { sub: ['-l'] },
+  passwd: { sub: ['-S'] },
+  chage: { sub: ['-l'] },
+  visudo: { sub: ['-c'] },
+  export: { sub: ['-p'] },
+  declare: { sub: ['-p'] },
+  ulimit: { denyArgs: ['-n', '-u', '-c', '-f', '-s', '-t', '-v', '-m', '-l', '-p', '-q', '-r', '-x', '-i', '-e', '-d'] },
+};
+
+const RULES = { ...PURE_READ, ...CONSTRAINED };
+
+// 出现即整体判为「需留痕」的元字符（无法静态分析）
+const FORBID_SUBSTRINGS = ['>', '>>', 'tee', '$(', '`', '<(', '<<<', '< '];
+
+// 复合命令分隔符：拆开逐段判定，全段只读才放行
+const COMPOUND_SPLIT = /(;|&&|\|\||\|)/;
+
+let activeRules = RULES;
+
+/** 可选：从 JSON 覆盖内置白名单 */
+export function loadPolicy(policyPath) {
+  if (!policyPath) return;
+  try {
+    activeRules = JSON.parse(fs.readFileSync(policyPath, 'utf8'));
+  } catch (err) {
+    console.error(`[readonly_policy] 白名单加载失败，回退内置规则: ${err.message}`);
+  }
+}
+
+/** 单段命令（无复合分隔符）的判定 */
+function isSingleReadonly(segment) {
+  const trimmed = segment.trim();
+  if (!trimmed) return true;
+
+  for (const bad of FORBID_SUBSTRINGS) {
+    if (trimmed.includes(bad)) return false;
+  }
+
+  const tokens = trimmed.split(/\s+/).filter(Boolean);
+  if (tokens.length === 0) return true;
+
+  // 命令名：去掉路径、把 - 归一为 _
+  const bin = tokens[0].split('/').pop().replace(/-/g, '_');
+
+  // 查合并后的规则表（不要直接查 PURE_READ —— 否则 CONSTRAINED 里的同名约束会被绕过）
+  const rule = RULES[bin];
+  if (!rule) return false;                       // 不在白名单 → 默认拒绝
+  if (rule === 1) return true;                   // 纯查看命令，无参数约束
+
+  // 子命令约束：允许出现的子命令/位置参数，命中任一即通过
+  if (Array.isArray(rule.sub) && rule.sub.length > 0) {
+    if (!tokens.slice(1).some((t) => rule.sub.includes(t))) return false;
+  }
+
+  // 危险参数约束
+  if (Array.isArray(rule.denyArgs)) {
+    for (const bad of rule.denyArgs) {
+      if (tokens.includes(bad)) return false;
+    }
+  }
+
+  // 语义级写操作拦截
+  if (rule.denyPattern && rule.denyPattern.test(trimmed)) return false;
+
+  // 内容形态约束（如 SQL 必须是 SELECT/SHOW）
+  if (rule.requirePattern && !rule.requirePattern.test(trimmed)) return false;
+
+  return true;
+}
+
+/**
+ * 判定整条命令是否只读。
+ * 复合命令（; && || |）拆开后逐段判定，全部只读才返回 true。
+ */
+export function isReadonly(command) {
+  if (!command || !command.trim()) return false;
+
+  // 权限提升一律不放行
+  if (/(^|\s)(sudo|su|doas|pkexec)(\s|$)/.test(command)) return false;
+
+  const segments = command.split(COMPOUND_SPLIT).filter(
+    (s) => s && ![';', '&&', '||', '|'].includes(s.trim())
+  );
+  if (segments.length === 0) return false;
+
+  return segments.every(isSingleReadonly);
+}
+
+/**
+ * 决定命令走哪条通道。
+ *
+ * 优先级：
+ *   1. audit === 'force'  → 'shell'（强制留痕，即使命中白名单）
+ *   2. 命中只读白名单      → 'exec' （不留痕）
+ *   3. 其余               → 'shell'（留痕）
+ *
+ * 注意：不提供 audit === 'off'。留痕保证不可被调用方关闭 ——
+ * 否则「变更操作走审计」就只是一句口号，而不是机制。
+ */
+export function resolveChannel(command, audit) {
+  if (audit === 'force') return { channel: 'shell', reason: 'audit=force 强制留痕' };
+  if (isReadonly(command)) return { channel: 'exec', reason: '命中只读白名单' };
+  return { channel: 'shell', reason: '非只读命令，默认留痕' };
+}
+
+export const _rules = { PURE_READ, CONSTRAINED };

package/ssh_manager.js

@@ -1,7 +1,50 @@
+/**
+ * ssh_manager.js —— 改造版
+ *
+ * 相对原版的唯一结构性改动：execCommand 会按命令性质选择 SSH 通道。
+ *
+ *   只读命令   → exec 通道  → koko 归为「命令执行」→ 不产生录像（快、干净）
+ *   非只读命令 → shell 通道 → koko 归为「正常会话」→ 完整录像（审计留痕）
+ *
+ * 依据：实测证明 koko 按 SSH 通道类型决定是否录像，与是否分配 PTY 无关。
+ *   exec()              → type: command → error_reason: replay_unsupported
+ *   exec({pty:true})    → type: command → error_reason: replay_unsupported
+ *   shell({...pty})     → type: normal  → has_replay: true
+ */
+
 import { Client } from 'ssh2';
 import { randomUUID } from 'crypto';
 import * as fs from 'fs';
 import * as path from 'path';
+import { resolveChannel } from './readonly_policy.js';
+
+// shell 通道的超时兜底（命令卡住时哨兵不出现，必须强退，否则 MCP 调用悬挂）
+// 可用环境变量 SSH_SHELL_TIMEOUT_MS 覆盖
+const SHELL_TIMEOUT_MS = Number(process.env.SSH_SHELL_TIMEOUT_MS || 30000);
+
+// 哨兵用的随机串。故意让「发送的命令行」里只出现 ${N} 而非展开值，
+// 这样 shell 回显的输入行不会与真实标记串冲突。
+const NONCE = '7f3a2c';
+const START_MARK = `__CMD_BEGIN_${NONCE}__`;
+const END_MARK = `__CMD_END_${NONCE}__`;
+
+// ANSI / OSC / 控制字符清洗
+const OSC_RE = /\u001B\][^\u0007\u001B]*(?:\u0007|\u001B\\)/g;
+const CSI_RE = /[\u001B\u009B][[\]()#;?]*(?:(?:\d{1,4}(?:;\d{0,4})*)?[0-9A-PRZcf-nqry=><])/g;
+const CTRL_RE = /[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F]/g;
+
+export function stripAnsi(s) {
+  return String(s)
+    .replace(OSC_RE, '')
+    .replace(CSI_RE, '')
+    .replace(CTRL_RE, '')
+    .replace(/\r/g, '');
+}
+
+// 去掉首尾空行
+function trimBlank(s) {
+  return s.replace(/^\n+/, '').replace(/\n+$/, '');
+}
 
 class SSHSession {
   constructor(sessionId, client, config) {
@@ -34,16 +77,14 @@ class SSHConnectionManager {
 
       const timeout = setTimeout(() => {
         client.end();
-        resolve({
-          success: false,
-          error: 'Connection timeout',
-          errorType: 'Timeout',
-        });
+        resolve({ success: false, error: 'Connection timeout', errorType: 'Timeout' });
       }, (options.timeout || 10) * 1000);
 
       client.on('ready', () => {
         clearTimeout(timeout);
-        const session = new SSHSession(sessionId, client, { host: config.host, port: config.port, username: config.username });
+        const session = new SSHSession(sessionId, client, {
+          host: config.host, port: config.port, username: config.username,
+        });
         this.sessions.set(sessionId, session);
         resolve({
           success: true,
@@ -57,11 +98,7 @@ class SSHConnectionManager {
 
       client.on('error', (err) => {
         clearTimeout(timeout);
-        resolve({
-          success: false,
-          error: err.message,
-          errorType: 'ConnectionError',
-        });
+        resolve({ success: false, error: err.message, errorType: 'ConnectionError' });
       });
 
       client.connect(config);
@@ -77,7 +114,18 @@ class SSHConnectionManager {
     }
   }
 
-  async execCommand(sessionId, command) {
+  // ---------------------------------------------------------------------------
+  // 通道选择入口
+  // ---------------------------------------------------------------------------
+
+  /**
+   * @param {string} sessionId
+   * @param {string} command
+   * @param {{audit?: 'force'|undefined}} [options]
+   *        audit === 'force' → 强制走 shell 通道留痕
+   *        其余情况由 readonly_policy 判定
+   */
+  async execCommand(sessionId, command, options = {}) {
     const session = this.sessions.get(sessionId);
     if (!session) {
       return {
@@ -87,15 +135,34 @@ class SSHConnectionManager {
       };
     }
 
+    const { channel, reason } = resolveChannel(command, options.audit);
+
+    const result = channel === 'shell'
+      ? await this._execViaShell(session, command)
+      : await this._execViaExec(session, command);
+
+    return { ...result, channel, channelReason: reason };
+  }
+
+  async execCommands(sessionId, commands, options = {}) {
+    const results = [];
+    for (const cmd of commands) {
+      const result = await this.execCommand(sessionId, cmd, options);
+      results.push(result);
+      if (!result.success) break;
+    }
+    return results;
+  }
+
+  // ---------------------------------------------------------------------------
+  // exec 通道：只读命令，快、干净、不产生审计记录
+  // ---------------------------------------------------------------------------
+
+  _execViaExec(session, command) {
     return new Promise((resolve) => {
       session.client.exec(command, (err, stream) => {
         if (err) {
-          resolve({
-            success: false,
-            error: err.message,
-            errorType: 'ExecError',
-            sessionId,
-          });
+          resolve({ success: false, error: err.message, errorType: 'ExecError', sessionId: session.sessionId });
           return;
         }
 
@@ -103,14 +170,7 @@ class SSHConnectionManager {
         let stderr = '';
 
         stream.on('close', (code) => {
-          resolve({
-            success: true,
-            sessionId,
-            command,
-            stdout,
-            stderr,
-            exitCode: code,
-          });
+          resolve({ success: true, sessionId: session.sessionId, command, stdout, stderr, exitCode: code });
         });
 
         stream.on('data', (data) => { stdout += data.toString(); });
@@ -119,24 +179,91 @@ class SSHConnectionManager {
     });
   }
 
-  async execCommands(sessionId, commands) {
-    const results = [];
-    for (const cmd of commands) {
-      const result = await this.execCommand(sessionId, cmd);
-      results.push(result);
-      if (!result.success) break;
-    }
-    return results;
+  // ---------------------------------------------------------------------------
+  // shell 通道：非只读命令，产生可回放的 JumpServer 会话
+  // ---------------------------------------------------------------------------
+
+  _execViaShell(session, command) {
+    return new Promise((resolve) => {
+      session.client.shell(
+        { term: 'xterm-256color', cols: 200, rows: 50 },
+        (err, stream) => {
+          if (err) {
+            resolve({ success: false, error: err.message, errorType: 'ShellError', sessionId: session.sessionId });
+            return;
+          }
+
+          let buf = '';
+          let settled = false;
+
+          const finish = (payload) => {
+            if (settled) return;
+            settled = true;
+            clearTimeout(timer);
+            try { stream.end(); } catch { /* ignore */ }
+            resolve({ ...payload, sessionId: session.sessionId, command });
+          };
+
+          const timer = setTimeout(() => {
+            // 超时也要交出已捕获的输出：命令可能是 exit / exec 这类
+            // 会直接终止 shell 的，哨兵永远不会出现
+            const k = buf.indexOf(START_MARK);
+            const partial = k === -1
+              ? ''
+              : trimBlank(stripAnsi(buf.slice(k + START_MARK.length)));
+            finish({
+              success: false,
+              error: `命令超时（${SHELL_TIMEOUT_MS}ms）。会话已在 JumpServer 留痕`,
+              errorType: 'Timeout',
+              stdout: partial,
+              exitCode: null,
+            });
+          }, SHELL_TIMEOUT_MS);
+
+          stream.on('data', (d) => {
+            buf += d.toString();
+
+            const i = buf.indexOf(START_MARK);
+            if (i === -1) return;
+            const j = buf.indexOf(END_MARK, i + START_MARK.length);
+            if (j === -1) return;
+
+            // 退出码：END_MARK 之后紧跟的数字
+            const tail = buf.slice(j + END_MARK.length);
+            const m = tail.match(/^(\d+)/);
+            if (!m) return;   // 退出码还没回显完，继续等
+
+            const body = buf.slice(i + START_MARK.length, j);
+
+            finish({
+              success: true,
+              stdout: trimBlank(stripAnsi(body)),
+              // pty 下 stderr 与 stdout 合并，内容都在 stdout 里
+              stderr: '',
+              exitCode: parseInt(m[1], 10),
+              note: '该会话已由 JumpServer 录像，可在控制台回放',
+            });
+          });
+
+          stream.stderr.on('data', (d) => { buf += d.toString(); });
+
+          // 用 shell 变量包住标记，避免回显行与真实标记串冲突；
+          // 注意必须写 ${N} 而非 $N —— 下划线是合法变量名字符，
+          // $N__ 会被 bash 解析成变量 N__（未定义），标记串就生成不出来。
+          stream.write(
+            `N=${NONCE}; echo "__CMD_BEGIN_\${N}__"; ${command}; echo "__CMD_END_\${N}__$?"\n`
+          );
+        }
+      );
+    });
   }
 
+  // ---------------------------------------------------------------------------
+
   disconnect(sessionId) {
     const session = this.sessions.get(sessionId);
     if (!session) {
-      return {
-        success: false,
-        error: `Session ${sessionId} not found`,
-        errorType: 'SessionNotFound',
-      };
+      return { success: false, error: `Session ${sessionId} not found`, errorType: 'SessionNotFound' };
     }
 
     try {
@@ -149,7 +276,7 @@ class SSHConnectionManager {
   }
 
   listSessions() {
-    const sessions = Array.from(this.sessions.values()).map(s => ({
+    const sessions = Array.from(this.sessions.values()).map((s) => ({
       sessionId: s.sessionId,
       host: s.config.host,
       username: s.config.username,