@zicolasjac-ai/remote-readonly-ssh 1.3.0 → 1.4.0

package/README.md

@@ -82,6 +82,7 @@ rrs <tool> [arg] [--host <ip>] [--config <file>] [--json]
 | `allowed_command_prefixes` | 只读命令前缀白名单（cat/ls/grep/ps/ss/tail...） |
 | `allowed_path_prefixes` | 允许读取的路径前缀 |
 | `blocked_paths` | 敏感路径黑名单（shadow/passwd/密钥/家目录） |
+| `container_exec` | 可选：`docker exec` 容器只读策略（允许子命令、路径前缀、递归路径前缀、超时、输出上限） |
 
 > **凭据安全提示**：密码为明文存放于本机 `config.json`（与私钥文件同级信任，仅本机可读）。Windows 建议收紧 ACL，Linux/macOS 建议 `chmod 600 ~/.rrs/config.json`。
 >
@@ -138,6 +139,7 @@ npm test          # 运行单元测试（node --test）
 - **主机密钥 TOFU**：堡垒机公钥指纹首见记录（`~/.rrs/known_hosts.json`）、每次连接比对，变化即拒绝（防中间人窃取凭据/会话）；连接错误消息中的凭据类内容自动脱敏。
 - **凭据不落命令行**：认证走 ssh2 库内存参数，密码/私钥不出现在进程参数与环境变量中；审计日志只记命令，不含凭据。
 - **直连模式同样受只读强制**：`direct: true` 仅跳过堡垒机菜单选资产环节，命令前缀白名单 / 禁止模式 / 路径黑名单 / 主机白名单 / 审计 / TOFU 对直连主机完全等效——防护不依赖堡垒机这道外部闸门。
+- **容器只读命令加固**：`docker exec` 受 `container_exec` 限制，仅允许配置内子命令与路径前缀；递归扫描只允许日志目录；实际执行自动包 `timeout`、`head -c` 输出截断和完成 marker，避免无输出命令卡住会话。
 - **无写原语**：工具集中不存在任何写操作路径；写操作由人工执行，本工具只读。
 
 **已知边界**（设计取舍）：

package/config.example.json

@@ -75,6 +75,13 @@
     "^diff(\\s+-[A-Za-z]+)?\\s+/[^\\s]+\\s+/[^\\s]+\\s*$",
     "^find\\s+/"
   ],
+  "container_exec": {
+    "allowed_subcommands": ["ps", "nvidia-smi", "ls", "grep", "head", "tail", "cat"],
+    "allowed_path_prefixes": ["/workspace/ds-dev"],
+    "recursive_path_prefixes": ["/workspace/ds-dev/logs"],
+    "timeout_seconds": 10,
+    "max_output_bytes": 500000
+  },
   "allowed_path_prefixes": [
     "/usr/local/nginx/",
     "/etc/nginx/",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zicolasjac-ai/remote-readonly-ssh",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "只读 SSH 运维 CLI 与 Agent Skill：通过 JumpServer 堡垒机白名单强制执行只读查询；认证组支持 SSH 私钥/密码两种模式与按 IP 分组；附 SKILL.md 让 opencode / Claude Code / Cursor 等 AI 助手自动发现并正确调用。",
   "license": "MIT",
   "bin": {

package/skills/remote-readonly-ssh/SKILL.md

@@ -95,6 +95,8 @@ rrs <tool> [arg] [--host <ip>] [--config <file>] [--json]
 2. **永远不要**用 `read-file` 读 `blocked_paths`（`/etc/passwd`、`/etc/shadow`、`~/.ssh/id_*` 等）
 3. **永远不要**指定未在 `target_hosts` 注册的 IP
 4. **不要**试图把 `;` `&&` `|` `>` `$()` 拼到参数里——所有路径和参数都做严格字符集校验
+5. **容器命令只走受控路径**：若使用 `docker exec`，必须遵守 `container_exec.allowed_path_prefixes`；默认只允许 `/workspace/ds-dev` 这类明确前缀，`grep -r` 只允许递归配置中的日志目录，禁止 `bash/sh`、`tail -f`、`ls -R`、相对路径和越界路径。
+6. **修改 `~/.rrs/config.json` 前必须先征得用户确认**（`~/.rrs/` 下的所有文件均如此，含白名单、target_hosts、认证组、known_hosts）。被拒绝时不要直接动手改配置：先把需要的路径/主机/变更内容展示给用户，等用户明确同意后再编辑。配置文件属于用户资产，不在工具的只读授权范围内自行变更。
 
 被拒绝的尝试一样会进审计日志。
 

package/src/config.js

@@ -102,6 +102,27 @@ function validateConfig(conf) {
     }
   }
 
+  const exec = conf.container_exec;
+  if (exec !== undefined) {
+    if (!exec || typeof exec !== "object" || Array.isArray(exec)) {
+      errors.push("container_exec 必须是对象 {allowed_subcommands, allowed_path_prefixes, recursive_path_prefixes, timeout_seconds, max_output_bytes}");
+    } else {
+      for (const key of ["allowed_subcommands", "allowed_path_prefixes", "recursive_path_prefixes"]) {
+        if (exec[key] !== undefined) {
+          if (!Array.isArray(exec[key]) || !exec[key].every((x) => typeof x === "string" && x)) {
+            errors.push(`container_exec.${key} 必须是非空字符串数组`);
+          }
+        }
+      }
+      if (exec.timeout_seconds !== undefined && (!Number.isInteger(exec.timeout_seconds) || exec.timeout_seconds < 1 || exec.timeout_seconds > 30)) {
+        errors.push(`container_exec.timeout_seconds 必须是 1-30 的整数，当前: ${exec.timeout_seconds}`);
+      }
+      if (exec.max_output_bytes !== undefined && (!Number.isInteger(exec.max_output_bytes) || exec.max_output_bytes < 1024 || exec.max_output_bytes > 2000000)) {
+        errors.push(`container_exec.max_output_bytes 必须是 1024-2000000 的整数，当前: ${exec.max_output_bytes}`);
+      }
+    }
+  }
+
   if (errors.length) throw cfgError(errors.join("；"));
   return true;
 }

package/src/jumpshell.js

@@ -5,9 +5,42 @@ const path = require("path");
 const crypto = require("crypto");
 const { Client } = require("ssh2");
 const { configDir } = require("./config");
+const { containerExecConf } = require("./whitelist");
 
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 
+function shellQuote(s) {
+  return "'" + String(s).replace(/'/g, "'\"'\"'") + "'";
+}
+
+function randomMarker() {
+  return Date.now().toString(36) + Math.random().toString(36).slice(2, 10);
+}
+
+function buildGuardedCommand(cmd, opts = {}) {
+  const timeoutSecs = Number.isInteger(opts.timeout_seconds) ? opts.timeout_seconds : 10;
+  const outputLimit = Number.isInteger(opts.max_output_bytes) ? opts.max_output_bytes : 500000;
+  const marker = randomMarker();
+  const a = marker.slice(0, Math.max(0, marker.length - 4));
+  const b = marker.slice(-4);
+  const q = shellQuote(cmd);
+  const line =
+    `RRS_MARKER_A=${a}; RRS_MARKER_B=${b}; ` +
+    `{ if command -v timeout >/dev/null 2>&1; then timeout -k 1 -s KILL ${timeoutSecs} sh -c ${q}; ` +
+    `else sh -c ${q}; fi; } | head -c ${outputLimit}; ` +
+    'echo "${RRS_MARKER_A}${RRS_MARKER_B}"';
+  return { line, marker };
+}
+
+function stripGuardedEcho(text) {
+  const tail = 'echo "${RRS_MARKER_A}${RRS_MARKER_B}"';
+  const idx = text.indexOf(tail);
+  if (idx < 0) return text;
+  const nl = text.indexOf("\n", idx);
+  if (nl < 0) return text.slice(0, idx);
+  return text.slice(nl + 1);
+}
+
 // 行尾 shell prompt（$/#/% 可带 ~ 家目录前缀，如 "user@host:~$ "）
 // 注意: 不能用 ">"，会与 JumpServer 菜单行 "Opt>" 冲突
 const PROMPT_RE = /(?:^|\r?\n)[^\r\n]*~?[$#%]\s*$/;
@@ -250,6 +283,16 @@ class JumpShell {
     return false;
   }
 
+  async waitForMarker(marker, deadline) {
+    while (Date.now() < deadline) {
+      if (this.terminated) throw new Error("SSH 连接已断开");
+      this.checkErr();
+      if (this.out.includes(marker)) return true;
+      await sleep(150);
+    }
+    return false;
+  }
+
   async login(timeoutSecs = 30) {
     const deadline = Date.now() + timeoutSecs * 1000;
     if (this.direct) {
@@ -270,14 +313,25 @@ class JumpShell {
 
   async runCmds(cmds, timeoutSecs = 30) {
     const deadline = Date.now() + timeoutSecs * 1000;
-    const start = this.out.length;
+    const execConf = containerExecConf(this.conf);
+    let result = "";
     for (const c of cmds) {
       if (Date.now() >= deadline) throw new Error("命令执行总超时");
-      const snapshot = this.out.length;
-      this.send(c);
-      if (!(await this.waitPromptAfter(snapshot, deadline))) throw new Error(`等待命令执行完成超时: ${c}`);
+      const remaining = Math.max(1, Math.floor((deadline - Date.now()) / 1000));
+      const innerTimeout = Math.max(1, Math.min(execConf.timeout_seconds, remaining - 1));
+      const { line, marker } = buildGuardedCommand(c, {
+        timeout_seconds: innerTimeout,
+        max_output_bytes: execConf.max_output_bytes,
+      });
+      const start = this.out.length;
+      this.send(line);
+      if (!(await this.waitForMarker(marker, deadline))) throw new Error(`等待命令执行完成超时: ${c}`);
+      const chunk = this.out.slice(start);
+      const markerIdx = chunk.indexOf(marker);
+      const output = markerIdx >= 0 ? chunk.slice(0, markerIdx) : chunk;
+      result += stripGuardedEcho(output);
     }
-    return this.out.slice(start);
+    return result;
   }
 
   close() {
@@ -297,4 +351,5 @@ module.exports = {
   JumpShell, cleanAnsi, sleep, PROMPT_RE,
   resolveHostEntry, resolveProfile, mapConnError,
   knownHostsPath, loadKnownHosts, saveKnownHosts, hostKeyFingerprint, checkHostKey,
+  shellQuote, buildGuardedCommand, stripGuardedEcho,
 };

package/src/whitelist.js

@@ -48,12 +48,99 @@ function splitPipeline(cmd) {
 // 提取命令中所有绝对路径 token（供 blocked_paths 黑名单核查）
 function extractAbsPaths(cmd) {
   const out = [];
-  for (const m of cmd.matchAll(/(?:^|[\s'"])(\/[A-Za-z0-9._\-/]+)/g)) {
+  for (const m of cmd.matchAll(/(?:^|[\s'"])(\/[A-Za-z0-9._\-/]*)/g)) {
     out.push(path.posix.normalize(m[1]));
   }
   return out;
 }
 
+const DEFAULT_CONTAINER_EXEC = {
+  allowed_subcommands: ["ps", "nvidia-smi", "ls", "grep", "head", "tail", "cat"],
+  allowed_path_prefixes: ["/workspace/ds-dev"],
+  recursive_path_prefixes: ["/workspace/ds-dev/logs"],
+  timeout_seconds: 10,
+  max_output_bytes: 500000,
+};
+
+function containerExecConf(conf) {
+  const c = conf.container_exec || {};
+  return {
+    allowed_subcommands: Array.isArray(c.allowed_subcommands) && c.allowed_subcommands.length
+      ? new Set(c.allowed_subcommands)
+      : new Set(DEFAULT_CONTAINER_EXEC.allowed_subcommands),
+    allowed_path_prefixes: Array.isArray(c.allowed_path_prefixes) && c.allowed_path_prefixes.length
+      ? c.allowed_path_prefixes
+      : DEFAULT_CONTAINER_EXEC.allowed_path_prefixes,
+    recursive_path_prefixes: Array.isArray(c.recursive_path_prefixes) && c.recursive_path_prefixes.length
+      ? c.recursive_path_prefixes
+      : DEFAULT_CONTAINER_EXEC.recursive_path_prefixes,
+    timeout_seconds: Number.isInteger(c.timeout_seconds) ? c.timeout_seconds : DEFAULT_CONTAINER_EXEC.timeout_seconds,
+    max_output_bytes: Number.isInteger(c.max_output_bytes) ? c.max_output_bytes : DEFAULT_CONTAINER_EXEC.max_output_bytes,
+  };
+}
+
+function stripContainerExecPrefixes(seg) {
+  return String(seg).trim().replace(
+    /^(?:timeout\s+\d+\s+|nice\s+-n\s+\d+\s+|ionice\s+-c\s+\d+\s+)+/,
+    ""
+  );
+}
+
+function parseContainerExec(seg) {
+  const stripped = stripContainerExecPrefixes(seg);
+  const m = stripped.match(/^docker\s+exec\s+([A-Za-z0-9._-]+)\s+(.*)$/s);
+  if (!m) return null;
+  const args = m[2].trim();
+  const sub = args.split(/\s+/)[0] || "";
+  return { container: m[1], args, sub };
+}
+
+function hasPathPrefix(p, prefixes) {
+  return prefixes.some((pref) => p === pref || p.startsWith(`${pref}/`));
+}
+
+function assertPathsAllowed(args, prefixes, cmdLine, what) {
+  const paths = extractAbsPaths(args);
+  if (paths.length === 0) {
+    throw new Error(`拒绝: ${what} 必须显式给出白名单目录下的绝对路径 [${cmdLine}]`);
+  }
+  for (const p of paths) {
+    if (!hasPathPrefix(p, prefixes)) {
+      throw new Error(`拒绝: ${what} 路径不在容器只读白名单 [${p}]（整条: ${cmdLine}）`);
+    }
+  }
+}
+
+function validateContainerExecSeg(seg, conf) {
+  const parsed = parseContainerExec(seg);
+  if (!parsed) return;
+  const cfg = containerExecConf(conf);
+  const { args, sub } = parsed;
+  if (!cfg.allowed_subcommands.has(sub)) {
+    throw new Error(`拒绝: 容器内子命令不在白名单 [${sub}]（整条: ${seg}）`);
+  }
+  if (sub === "ps") {
+    if (args !== "ps -ef") throw new Error(`拒绝: 容器内 ps 仅允许固定形式 [docker exec ... ps -ef]（整条: ${seg}）`);
+    return;
+  }
+  if (sub === "nvidia-smi") {
+    if (args !== "nvidia-smi") throw new Error(`拒绝: 容器内 nvidia-smi 不允许附加参数（整条: ${seg}）`);
+    return;
+  }
+  if (sub === "ls" && (/(?:^|\s)-[A-Za-z]*R[A-Za-z]*(?=\s|$)/.test(args) || /--recursive/.test(args))) {
+    throw new Error(`拒绝: 容器内禁止递归 ls（整条: ${seg}）`);
+  }
+  if (sub === "tail" && (/(?:^|\s)-f(?:\s|$)|--follow/.test(args))) {
+    throw new Error(`拒绝: 容器内 tail 禁止 -f/--follow（整条: ${seg}）`);
+  }
+  if (sub === "head" && (/(?:^|\s)-f(?:\s|$)|--follow/.test(args))) {
+    throw new Error(`拒绝: 容器内 head 禁止 -f/--follow（整条: ${seg}）`);
+  }
+  const isRecursive = (/(?:^|\s)-[A-Za-z]*[rR][A-Za-z]*(?=\s|$)/.test(args) || /--recursive/.test(args));
+  const pathPrefixes = isRecursive ? cfg.recursive_path_prefixes : cfg.allowed_path_prefixes;
+  assertPathsAllowed(args, pathPrefixes, seg, sub);
+}
+
 function validateCmd(cmd, conf) {
   const c = String(cmd).trim();
   if (!c) throw new Error("空命令");
@@ -68,6 +155,9 @@ function validateCmd(cmd, conf) {
       throw new Error(`拒绝: 命令段不在白名单 [${seg}]（整条: ${c}）`);
     }
   }
+  for (const seg of splitPipeline(c)) {
+    validateContainerExecSeg(seg, conf);
+  }
   for (const pat of FORBIDDEN_PATTERNS) {
     if (pat.test(c)) throw new Error(`拒绝: 命中禁止模式 [${pat}] 命令 [${c}]`);
   }
@@ -134,4 +224,12 @@ function validateBin(bin, conf) {
   return b;
 }
 
-module.exports = { validateCmd, validatePath, validateHost, validateArg, validateBin };
+module.exports = {
+  validateCmd,
+  validatePath,
+  validateHost,
+  validateArg,
+  validateBin,
+  containerExecConf,
+  DEFAULT_CONTAINER_EXEC,
+};