@zicolasjac-ai/remote-readonly-ssh 1.0.3 → 1.1.0

package/README.md

@@ -18,6 +18,8 @@ npm install -g @zicolasjac-ai/remote-readonly-ssh
 
 要求 Node.js >= 18，系统已装 OpenSSH 客户端（Windows 10+ / Linux / macOS 自带）。
 
+> 从旧包名 `remote-readonly-ssh`（v1.0.0）升级的用户，请先 `npm uninstall -g remote-readonly-ssh` 再安装，否则会报 `EEXIST: file already exists`。
+
 ## 快速开始
 
 ```bash
@@ -30,9 +32,11 @@ rrs sys-info
 ## 用法
 
 ```
-rrs <tool> [arg] [--host <ip>] [--config <file>]
+rrs <tool> [arg] [--host <ip>] [--config <file>] [--json]
 ```
 
+`--json` 以 JSON 输出结果（`{"ok":true,"tool":...,"host":...,"output":...}`），便于脚本/AI 调用；`-v` / `--version` 查看版本。
+
 | 工具 | 说明 |
 |------|------|
 | `init` | 生成配置模板 `~/.rrs/config.json` |
@@ -52,6 +56,8 @@ rrs <tool> [arg] [--host <ip>] [--config <file>]
 | 键 | 说明 |
 |-----|------|
 | `jump_server` | 堡垒机地址 / 端口 / 用户名 |
+| `ssh_options` | 附加 ssh 参数（默认 `StrictHostKeyChecking=no`、兼容旧堡垒机的 ssh-rsa 算法开关，可按需调整） |
+| `audit` | `enabled`（默认 true，关闭则不留痕）与 `include_output`（默认 false，true 时把命令输出摘要写入审计日志） |
 | `private_key_path` | SSH 私钥路径（Windows 建议放 `~/.ssh/locked/` 收紧 ACL；Linux/Mac 用 `chmod 600`） |
 | `target_hosts` | 允许访问的目标主机白名单 `{ip: 堡垒机搜索关键字}` |
 | `allowed_version_bins` | 允许执行 `-v/-V` 的二进制白名单 |
@@ -61,6 +67,12 @@ rrs <tool> [arg] [--host <ip>] [--config <file>]
 
 审计日志：`~/.rrs/audit.log`
 
+## 开发
+
+```bash
+npm test          # 运行单元测试（node --test）
+```
+
 ## 安全模型
 
 - **双层校验**：每条命令必须以允许前缀开头，且不得含禁止模式（rm/mv/vi/systemctl/sudo/重定向到文件/shadow/ssh 密钥等），否则一律拒绝。

package/bin/rrs.js

@@ -24,20 +24,23 @@ function printUsage() {
     ["exec-only <cmd>", "通用只读命令（前缀白名单+禁止模式）"],
   ];
   console.log("rrs — 只读 SSH 运维 CLI（白名单强制，零写能力）\n");
-  console.log("用法: rrs <工具> [参数] [--host <ip>] [--config <file>]\n");
+  console.log("用法: rrs <工具> [参数] [--host <ip>] [--config <file>] [--json]\n");
+  console.log("选项: --json 以 JSON 输出结果（便于脚本/AI 调用）; -v/--version 查看版本\n");
   for (const [k, v] of cmds) {
     console.log(`  ${k.padEnd(22)} ${v}`);
   }
 }
 
 function parseArgs(argv) {
-  const opts = { tool: null, arg: null, host: null, config: null };
+  const opts = { tool: null, arg: null, host: null, config: null, version: false, json: false };
   const rest = [];
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     if (a === "--host") opts.host = argv[++i];
     else if (a === "--config") opts.config = argv[++i];
     else if (a === "-h" || a === "--help") { opts.tool = "help"; }
+    else if (a === "-v" || a === "--version") opts.version = true;
+    else if (a === "--json") opts.json = true;
     else rest.push(a);
   }
   opts.tool = opts.tool || rest[0] || "help";
@@ -102,20 +105,30 @@ function listTools(conf) {
   console.log(`\n允许主机: ${Object.keys(conf.target_hosts || {}).join(", ")}`);
   console.log(`允许查版本: ${(conf.allowed_version_bins || []).join(", ")}`);
   console.log(`允许读路径前缀: ${(conf.allowed_path_prefixes || []).join(", ")}`);
-  console.log(`配置文件: ${process.env.READONLY_SSH_CONFIG || path.join(configDir(), "config.json")}`);
+  console.log(`配置文件: ${process.env.RRS_CONFIG || path.join(configDir(), "config.json")}`);
   console.log(`审计日志: ${path.join(configDir(), "audit.log")}`);
 }
 
+function emitResult(opts, data) {
+  if (opts.json) console.log(JSON.stringify(data));
+  else if (data.error) console.error(`[${data.kind || "错误"}] ${data.error}`);
+  else console.log(data.output);
+}
+
 async function main() {
   const opts = parseArgs(process.argv.slice(2));
-  if (opts.tool === "help" || opts.tool === "--help") { printUsage(); return; }
+  if (opts.version) {
+    console.log(require(path.join(PACKAGE_ROOT, "package.json")).version);
+    return;
+  }
+  if (opts.tool === "help") { printUsage(); return; }
   if (opts.tool === "init") { initConfig(); return; }
 
   let conf;
   try {
     conf = loadConf(opts.config);
   } catch (e) {
-    console.error(`[错误] ${e.message}`);
+    emitResult(opts, { ok: false, error: e.message, kind: "错误" });
     process.exit(e.exitCode || 1);
   }
 
@@ -126,8 +139,8 @@ async function main() {
     host = validateHost(opts.host || Object.keys(conf.target_hosts || {})[0], conf);
     cmds = buildCmds(opts.tool, opts.arg, conf);
   } catch (e) {
-    audit(configDir(), opts.tool, opts.host || "", [], false, e.message);
-    console.error(`[拒绝] ${e.message}`);
+    audit(conf, opts.tool, opts.host || "", [], false, e.message);
+    emitResult(opts, { ok: false, tool: opts.tool, host: opts.host || "", error: e.message, kind: "拒绝" });
     process.exit(2);
   }
 
@@ -136,15 +149,20 @@ async function main() {
     shell.connect();
     await shell.login();
     const out = await shell.runCmds(cmds);
-    console.log(cleanAnsi(out));
-    audit(configDir(), opts.tool, host, cmds, true);
+    const cleaned = cleanAnsi(out);
+    emitResult(opts, { ok: true, tool: opts.tool, host, output: cleaned });
+    audit(conf, opts.tool, host, cmds, true, undefined, cleaned);
   } catch (e) {
-    audit(configDir(), opts.tool, host, cmds, false, e.message);
-    console.error(`[错误] ${e.message}`);
+    audit(conf, opts.tool, host, cmds, false, e.message);
+    emitResult(opts, { ok: false, tool: opts.tool, host, error: e.message, kind: "错误" });
     process.exit(1);
   } finally {
     shell.close();
   }
 }
 
-main();
+if (require.main === module) {
+  main();
+}
+
+module.exports = { parseArgs, buildCmds, printUsage };

package/config.example.json

@@ -4,6 +4,15 @@
     "port": 2222,
     "username": "YOUR_USERNAME"
   },
+  "ssh_options": [
+    "-o", "StrictHostKeyChecking=no",
+    "-o", "HostKeyAlgorithms=+ssh-rsa",
+    "-o", "PubkeyAcceptedAlgorithms=+ssh-rsa"
+  ],
+  "audit": {
+    "enabled": true,
+    "include_output": false
+  },
   "private_key_path": "C:\\Users\\YOURNAME\\.ssh\\id_rsa",
   "target_hosts": {
     "10.0.0.1": "10.0.0",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zicolasjac-ai/remote-readonly-ssh",
-  "version": "1.0.3",
+  "version": "1.1.0",
   "description": "只读 SSH 运维 CLI：基于白名单强制校验，通过堡垒机对服务器执行只读查询，设计上零写权限。",
   "license": "MIT",
   "bin": {
@@ -30,6 +30,6 @@
   ],
   "dependencies": {},
   "scripts": {
-    "test": "node --test test/"
+    "test": "node --test"
   }
 }

package/src/config.js

@@ -21,7 +21,7 @@ function loadConf(confPath) {
   if (!fs.existsSync(resolved)) {
     const err = new Error(
       `找不到配置文件 ${resolved}\n` +
-      `请先运行 readonly-ssh init 生成模板，再填入您的跳板机/资产/密钥信息。`
+      `请先运行 rrs init 生成模板，再填入您的跳板机/资产/密钥信息。`
     );
     err.exitCode = 3;
     throw err;
@@ -70,9 +70,11 @@ function describeCmd(tool, cmd) {
   }
 }
 
-function audit(confDir, tool, host, cmds, ok, note) {
+function audit(conf, tool, host, cmds, ok, note, output, confDir) {
   try {
-    fs.mkdirSync(confDir, { recursive: true });
+    if (conf.audit && conf.audit.enabled === false) return;
+    const dir = confDir || configDir();
+    fs.mkdirSync(dir, { recursive: true });
     const d = new Date();
     const pad = (n) => String(n).padStart(2, "0");
     const local = `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())} ${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}`;
@@ -89,8 +91,13 @@ function audit(confDir, tool, host, cmds, ok, note) {
       lines.push(`    ${i + 1}. ${c}`);
       lines.push(`       用途: ${describeCmd(tool, c)}`);
     });
+    if (ok && output && conf.audit && conf.audit.include_output) {
+      const out = String(output).replace(/\x1b\[[0-9;?]*[A-Za-z]/g, "").trim();
+      lines.push(`  输出摘要:`);
+      lines.push(out.slice(0, 4000));
+    }
     lines.push(bar, "");
-    fs.appendFileSync(path.join(confDir, "audit.log"), lines.join("\n"), "utf8");
+    fs.appendFileSync(path.join(dir, "audit.log"), lines.join("\n"), "utf8");
   } catch {
     // 审计失败不阻断主流程
   }

package/src/jumpshell.js

@@ -4,6 +4,25 @@ const { spawn } = require("child_process");
 
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 
+// 行尾 shell prompt（$/#/% 可带 ~ 家目录前缀，如 "user@host:~$ "）
+// 注意: 不能用 ">"，会与 JumpServer 菜单行 "Opt>" 冲突
+const PROMPT_RE = /(?:^|\r?\n)[^\r\n]*~?[$#%]\s*$/;
+
+const ERR_PATTERNS = [
+  /permission denied/i,
+  /connection refused/i,
+  /connection timed out/i,
+  /host key verification failed/i,
+  /could not resolve hostname/i,
+  /no route to host/i,
+];
+
+const DEFAULT_SSH_OPTIONS = [
+  "-o", "StrictHostKeyChecking=no",
+  "-o", "HostKeyAlgorithms=+ssh-rsa",
+  "-o", "PubkeyAcceptedAlgorithms=+ssh-rsa",
+];
+
 /**
  * 通过系统 ssh 驱动 JumpServer 堡垒机菜单，登录目标资产并执行命令。
  * 仅负责"连接与收发"，命令校验在调用方（whitelist.js）完成。
@@ -14,27 +33,25 @@ class JumpShell {
     this.host = host;
     this.conf = conf;
     this.proc = null;
-    this.buf = "";
-    this.stopped = false;
+    this.out = "";
+    this.err = "";
+    this.terminated = false;
   }
 
   connect() {
     const js = this.conf.jump_server;
+    const opts = this.conf.ssh_options && this.conf.ssh_options.length
+      ? this.conf.ssh_options
+      : DEFAULT_SSH_OPTIONS;
     const args = [
       "-i", this.conf.private_key_path,
       "-p", String(js.port),
-      "-o", "StrictHostKeyChecking=no",
-      "-o", "HostKeyAlgorithms=+ssh-rsa",
-      "-o", "PubkeyAcceptedAlgorithms=+ssh-rsa",
+      ...opts,
       "-tt", `${js.username}@${js.host}`,
     ];
     this.proc = spawn("ssh", args, { stdio: ["pipe", "pipe", "pipe"], windowsHide: true });
-    this.proc.stdout.on("data", (d) => {
-      this.buf += d.toString("utf8");
-    });
-    this.proc.stderr.on("data", (d) => {
-      this.buf += d.toString("utf8");
-    });
+    this.proc.stdout.on("data", (d) => { this.out += d.toString("utf8"); });
+    this.proc.stderr.on("data", (d) => { this.err += d.toString("utf8"); });
   }
 
   send(s) {
@@ -43,51 +60,87 @@ class JumpShell {
     }
   }
 
-  async waitFor(marker, secs) {
-    const deadline = Date.now() + secs * 1000;
+  checkErr() {
+    for (const p of ERR_PATTERNS) {
+      if (p.test(this.err)) {
+        const last = this.err.trim().split("\n").pop();
+        throw new Error(`SSH 错误: ${last}`);
+      }
+    }
+  }
+
+  isPrompt() {
+    return PROMPT_RE.test(this.out);
+  }
+
+  async waitFor(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 waitPrompt(deadline) {
+    while (Date.now() < deadline) {
+      if (this.terminated) throw new Error("SSH 连接已断开");
+      this.checkErr();
+      if (this.isPrompt()) return true;
+      await sleep(150);
+    }
+    return false;
+  }
+
+  async waitPromptAfter(snapshot, deadline) {
     while (Date.now() < deadline) {
-      if (this.buf.includes(marker)) return true;
+      if (this.terminated) throw new Error("SSH 连接已断开");
+      this.checkErr();
+      if (this.out.length > snapshot && this.isPrompt()) return true;
       await sleep(150);
     }
     return false;
   }
 
-  async login() {
-    if (!(await this.waitFor("Opt>", 25))) throw new Error("跳板机菜单未出现");
+  async login(timeoutSecs = 30) {
+    const deadline = Date.now() + timeoutSecs * 1000;
+    if (!(await this.waitFor("Opt>", deadline))) throw new Error("跳板机菜单未出现");
     await sleep(1000);
     this.send("");
     await sleep(2000);
     this.send(this.searchKeyword);
-    if (!(await this.waitFor(this.host, 15))) throw new Error(`未找到目标资产 ${this.host}`);
-    if (!(await this.waitFor("~", 15))) throw new Error("未能进入 shell");
+    if (!(await this.waitFor(this.host, deadline))) throw new Error(`未找到目标资产 ${this.host}`);
+    if (!(await this.waitPrompt(deadline))) throw new Error("未能进入 shell");
     await sleep(500);
   }
 
-  async runCmds(cmds, waitSecs = 4) {
-    const start = this.buf.length;
+  async runCmds(cmds, timeoutSecs = 30) {
+    const deadline = Date.now() + timeoutSecs * 1000;
+    const start = this.out.length;
     for (const c of cmds) {
+      if (Date.now() >= deadline) throw new Error("命令执行总超时");
+      const snapshot = this.out.length;
       this.send(c);
-      await sleep(waitSecs * 1000);
+      if (!(await this.waitPromptAfter(snapshot, deadline))) throw new Error(`等待命令执行完成超时: ${c}`);
     }
-    return this.buf.slice(start);
+    return this.out.slice(start);
   }
 
   close() {
-    this.stopped = true;
-    try {
-      this.send("exit");
-      setTimeout(() => {
-        try { this.send("exit"); } catch {}
-        setTimeout(() => {
-          try { this.proc.kill(); } catch {}
-        }, 1000);
-      }, 1000);
-    } catch {}
+    this.terminated = true;
+    try { this.send("exit"); } catch {}
+    try { if (this.proc && this.proc.stdin) this.proc.stdin.end(); } catch {}
+    setTimeout(() => {
+      try { if (this.proc) this.proc.kill(); } catch {}
+    }, 1000);
   }
 }
 
 function cleanAnsi(t) {
-  return t.replace(/\x1b\[[0-9;?]*[A-Za-z]/g, "");
+  return t
+    .replace(/\x1b\][^\x07\x1b]*(\x07|\x1b\\)/g, "")   // OSC 序列（终端标题等）
+    .replace(/\x1b\[[0-9;?]*[A-Za-z]/g, "");           // CSI 序列（颜色/光标）
 }
 
-module.exports = { JumpShell, cleanAnsi, sleep };
+module.exports = { JumpShell, cleanAnsi, sleep, PROMPT_RE };

package/src/whitelist.js

@@ -4,7 +4,7 @@ const path = require("path");
 
 const FORBIDDEN_PATTERNS = [
   />\s*[^|&]/,           // output redirection to file (2>&1 stream redirect is allowed)
-  /\b(rm|mv|cp|tar|install|yum|dnf|apt-get|vi|vim|nano|mkdir|touch|chmod|chown|useradd|userdel|passwd|sudo|su|reboot|shutdown|systemctl|kill|pkill|wget|curl|nc)\b/,
+  /\b(rm|mv|cp|tar|install|yum|dnf|apt-get|vi|vim|nano|mkdir|touch|chmod|chown|useradd|userdel|passwd|sudo|su|reboot|shutdown|systemctl|kill|pkill|wget|curl|nc|tee|xargs|dd|bash|python|perl|ruby|awk|scp|sftp|rsync|git)\b/,
   /nginx\s+-s\b/,        // nginx signal controls (stop/quit/reload/reopen) are mutating
   /sed\s+-i\b/,          // sed in-place edit is mutating (defense in depth)
   /-exec\b|-execdir\b|-ok\b|-okdir\b/, // find exec actions run arbitrary commands
@@ -46,10 +46,12 @@ function validateCmd(cmd, conf) {
   return c;
 }
 
+const PATH_RE = /^[A-Za-z0-9._\-/:*]+$/;
+
 function validatePath(pathArg, conf) {
   const raw = String(pathArg).trim();
   if (!raw.startsWith("/")) throw new Error(`拒绝: 仅允许绝对路径 [${raw}]`);
-  if (raw.includes("\0")) throw new Error(`拒绝: 非法字符 [${raw}]`);
+  if (!PATH_RE.test(raw)) throw new Error(`拒绝: 路径含非法字符 [${raw}]`);
   // normalize resolves any . or .. segments BEFORE whitelist checks
   const p = path.posix.normalize(raw);
   const prefixes = conf.allowed_path_prefixes || [];
@@ -71,7 +73,8 @@ function validateHost(host, conf) {
 }
 
 function validateArg(arg, what) {
-  if (!arg || !ARG_RE.test(arg)) {
+  if (!arg) throw new Error(`拒绝: 缺少 ${what} 参数`);
+  if (!ARG_RE.test(arg)) {
     throw new Error(`拒绝: ${what} 含非法字符 [${arg}]`);
   }
   return arg;