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

package/README.md

@@ -7,6 +7,7 @@
 ## 为什么需要它
 
 - **技术强制只读**：命令前缀白名单 + 禁止模式 + 参数防注入 + 目标主机白名单，多层校验。
+- **主机密钥防中间人**：TOFU 校验——首次连接自动记录堡垒机公钥指纹（`~/.rrs/known_hosts.json`），之后每次连接比对，不一致直接拒绝。
 - **审计留痕**：每次调用（含被拒绝的记录）写入本地审计日志，可随时审查。
 - **极简依赖**：连接层用纯 JS 的 `ssh2`（无原生编译），认证组支持 **SSH 私钥 / 密码** 两种模式，可按 IP 分组配置（N 台主机共用一组凭据），跨平台行为一致。
 - **AI Agent 友好**：附带 SKILL.md 可一键安装到 opencode / Claude / Cursor / Windsurf / Codex / OpenHands 等 AI 助手的 skills 目录。
@@ -74,7 +75,7 @@ rrs <tool> [arg] [--host <ip>] [--config <file>] [--json]
 
 | 键 | 说明 |
 |-----|------|
-| `auth_profiles` | **认证组**（可多个）：`{组名: {host, port, username, auth}}`。`auth.mode` 支持 `key`（`private_key_path` 必填，可选 `private_key_passphrase`）与 `password`（`password` 必填）。`list-tools` 只显示模式与主机，不显示任何凭据 |
+| `auth_profiles` | **认证组**（可多个）：`{组名: {host, port, username, auth, direct?}}`。`auth.mode` 支持 `key`（`private_key_path` 必填，可选 `private_key_passphrase`）与 `password`（`password` 必填）。`direct: true` 表示**直连裸机**（跳过堡垒机菜单，适合无堡垒机的服务器；命令只读校验与堡垒机模式完全一致）。`list-tools` 只显示模式与主机，不显示任何凭据 |
 | `target_hosts` | 目标主机白名单 `{ip: {profile, keyword?}}`：`profile` 引用认证组名，`keyword` 为堡垒机资产搜索关键字（缺省用 IP）。**多台主机可共用同一认证组（N:1）** |
 | `audit` | `enabled`（默认 true，关闭则不留痕）与 `include_output`（默认 false，true 时把命令输出摘要写入审计日志） |
 | `allowed_version_bins` | 允许执行 `-v/-V` 的二进制白名单 |
@@ -83,6 +84,8 @@ rrs <tool> [arg] [--host <ip>] [--config <file>] [--json]
 | `blocked_paths` | 敏感路径黑名单（shadow/passwd/密钥/家目录） |
 
 > **凭据安全提示**：密码为明文存放于本机 `config.json`（与私钥文件同级信任，仅本机可读）。Windows 建议收紧 ACL，Linux/macOS 建议 `chmod 600 ~/.rrs/config.json`。
+>
+> **主机密钥校验**：首次连接堡垒机时自动记录其公钥指纹到 `~/.rrs/known_hosts.json`；此后密钥变化一律拒绝连接（防中间人）。若堡垒机确实已更换，删除该文件中对应条目重试即可重新记录。`init` 向导中密码输入**静音不回显**。
 
 审计日志：`~/.rrs/audit.log`
 
@@ -132,6 +135,9 @@ npm test          # 运行单元测试（node --test）
 - **防绕过加固**：路径 `..` 穿越规范化、通配符 glob（`/etc/*/shadow`）、反斜杠转义、命令替换（`$()`、反引号）、变量展开（`$HOME`）、波浪号（`~`）、分隔符（`;` `&` `&&`）、换行注入等攻击面全部封堵；`hostname <name>`、`date -s` 等状态变更命令拒绝。
 - **参数防注入**：`proc`/`ports`/`bin-version` 参数做严格字符集校验。
 - **主机白名单**：未登记 IP 一律拒绝。
+- **主机密钥 TOFU**：堡垒机公钥指纹首见记录（`~/.rrs/known_hosts.json`）、每次连接比对，变化即拒绝（防中间人窃取凭据/会话）；连接错误消息中的凭据类内容自动脱敏。
+- **凭据不落命令行**：认证走 ssh2 库内存参数，密码/私钥不出现在进程参数与环境变量中；审计日志只记命令，不含凭据。
+- **直连模式同样受只读强制**：`direct: true` 仅跳过堡垒机菜单选资产环节，命令前缀白名单 / 禁止模式 / 路径黑名单 / 主机白名单 / 审计 / TOFU 对直连主机完全等效——防护不依赖堡垒机这道外部闸门。
 - **无写原语**：工具集中不存在任何写操作路径；写操作由人工执行，本工具只读。
 
 **已知边界**（设计取舍）：

package/bin/rrs.js

@@ -126,7 +126,10 @@ function runSetup(opts) {
 
 function initConfig() {
   if (process.stdin.isTTY && process.stdout.isTTY) {
-    return initWizard.runInteractive();
+    return initWizard.runInteractive().catch((e) => {
+      console.error(`[init] ${e.message}`);
+      process.exit(1);
+    });
   }
   const dir = configDir();
   const dest = path.join(dir, "config.json");
@@ -137,7 +140,7 @@ function initConfig() {
   const tpl = fs.readFileSync(path.join(PACKAGE_ROOT, "config.example.json"), "utf8");
   fs.writeFileSync(dest, tpl, "utf8");
   console.log(`已生成配置模板: ${dest}`);
-  console.log("请填写 jump_server（跳板机）、private_key_path（私钥）、target_hosts（目标主机）后使用。");
+  console.log("请填写 auth_profiles（认证组：SSH 私钥或密码）、target_hosts（目标主机）后使用。");
 }
 
 function buildCmds(tool, arg, conf) {
@@ -181,7 +184,7 @@ function listTools(conf) {
   };
   for (const [k, v] of Object.entries(tools)) console.log(`  ${k.padEnd(20)} ${v}`);
   const profiles = conf.auth_profiles || {};
-  console.log(`\n认证组: ${Object.entries(profiles).map(([id, p]) => `${id}(${p.auth.mode}@${p.host})`).join(", ") || "(无)"}`);
+  console.log(`\n认证组: ${Object.entries(profiles).map(([id, p]) => `${id}(${p.auth.mode}@${p.host}${p.direct ? ",direct" : ""})`).join(", ") || "(无)"}`);
   console.log(`允许主机: ${Object.keys(conf.target_hosts || {}).join(", ")}`);
   console.log(`允许查版本: ${(conf.allowed_version_bins || []).join(", ")}`);
   console.log(`允许读路径前缀: ${(conf.allowed_path_prefixes || []).join(", ")}`);
@@ -234,7 +237,7 @@ async function main() {
 
   const shell = new JumpShell(conf, host);
   try {
-    shell.connect();
+    await shell.connect();
     await shell.login();
     const out = await shell.runCmds(cmds);
     const cleaned = cleanAnsi(out);

package/config.example.json

@@ -18,6 +18,16 @@
         "mode": "password",
         "password": "YOUR_PASSWORD"
       }
+    },
+    "profile_direct": {
+      "host": "YOUR_DIRECT_SERVER_IP",
+      "port": 22,
+      "username": "YOUR_USERNAME_3",
+      "direct": true,
+      "auth": {
+        "mode": "password",
+        "password": "YOUR_PASSWORD_2"
+      }
     }
   },
   "target_hosts": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zicolasjac-ai/remote-readonly-ssh",
-  "version": "1.2.0",
+  "version": "1.3.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

@@ -32,7 +32,8 @@ metadata:
 ```bash
 npm install -g @zicolasjac-ai/remote-readonly-ssh
 rrs init          # 生成配置模板 ~/.rrs/config.json
-# 编辑配置: auth_profiles（认证组，key/password 两种模式，可多个）/ target_hosts（IP → 认证组+搜索关键字，多 IP 可共用一组）
+# 编辑配置: auth_profiles（认证组，key/password 两种模式，可多个；direct:true 表示跳过堡垒机菜单直连裸机）
+#           target_hosts（IP → 认证组+搜索关键字，多 IP 可共用一组）
 rrs setup skills  # 把本 skill 安装到 opencode / claude / agents 等目录
 ```
 

package/src/config.js

@@ -60,6 +60,12 @@ function validateConfig(conf) {
       }
       if (!p.host || typeof p.host !== "string") errors.push(`认证组 [${id}] 缺少 host`);
       if (!p.username || typeof p.username !== "string") errors.push(`认证组 [${id}] 缺少 username`);
+      if (p.direct !== undefined && typeof p.direct !== "boolean") {
+        errors.push(`认证组 [${id}] direct 必须是布尔值（true=跳过堡垒机菜单直连）`);
+      }
+      if (p.port !== undefined && (!Number.isInteger(p.port) || p.port < 1 || p.port > 65535)) {
+        errors.push(`认证组 [${id}] port 必须是 1-65535 的整数，当前: ${p.port}`);
+      }
       const auth = p.auth;
       if (!auth || typeof auth !== "object" || Array.isArray(auth)) {
         errors.push(`认证组 [${id}] 缺少 auth {mode, ...}`);

package/src/init.js

@@ -3,6 +3,7 @@
 const fs = require("fs");
 const path = require("path");
 const os = require("os");
+const { Writable } = require("node:stream");
 const readline = require("node:readline/promises");
 const setupSkill = require("./setup");
 
@@ -83,6 +84,45 @@ function defaultAnswersFor(cfg) {
   };
 }
 
+/**
+ * 静音输入（TTY 下不回显，防肩窥）。
+ * 原理：临时把 readline 的 output 替换为吞字节流（屏蔽 readline 的按键回显），
+ * 自行逐字节收集（支持退格）；结束恢复原 output。
+ * 非标准环境（测试 mock / 管道，无 TTY）回退为普通 question（明文回显）。
+ */
+function askSecret(rl, q) {
+  const input = rl.input;
+  const output = rl.output;
+  if (!input || !output || input.isTTY !== true || typeof input.setRawMode !== "function") {
+    return Promise.resolve(rl.question(`${q}: `));
+  }
+  return new Promise((resolve, reject) => {
+    const silent = new Writable({
+      write(_chunk, _enc, cb) { cb(); },
+    });
+    rl.output = silent;
+    const wasRaw = input.isRaw;
+    input.setRawMode(true);
+    output.write(`${q}: `);
+    let buf = "";
+    const finish = (fn) => {
+      input.removeListener("data", onData);
+      try { input.setRawMode(wasRaw); } catch (_) {}
+      rl.output = output;
+      output.write("\n");
+      fn();
+    };
+    const onData = (ch) => {
+      const s = ch.toString("utf8");
+      if (s === "\r" || s === "\n") return finish(() => resolve(buf));
+      if (s === "\u0003") return finish(() => reject(new Error("已取消输入")));
+      if (s === "\u007f" || s === "\b") { buf = buf.slice(0, -1); return; }
+      if (s >= " ") buf += s;
+    };
+    input.on("data", onData);
+  });
+}
+
 async function collectAnswers(rl, cfg, prompt) {
   const ask = async (q, def) => {
     const label = def ? `${q} [${def}]` : q;
@@ -122,9 +162,9 @@ async function collectAnswers(rl, cfg, prompt) {
       let password = "";
       if (mode === "key") {
         privateKeyPath = await ask("  SSH 私钥绝对路径", def.defaultKey || path.join(os.homedir(), ".ssh", "id_rsa"));
-        passphrase = await ask("  私钥口令（无则留空）", "");
+        passphrase = (await askSecret(rl, "  私钥口令（无则留空）")).trim();
       } else {
-        password = await ask("  登录密码", "");
+        password = (await askSecret(rl, "  登录密码")).trim();
         if (!password) {
           throw new Error("跳过：未填写登录密码。请稍后编辑 " + path.join(os.homedir(), ".rrs", "config.json"));
         }

package/src/jumpshell.js

@@ -1,7 +1,10 @@
 "use strict";
 
 const fs = require("fs");
+const path = require("path");
+const crypto = require("crypto");
 const { Client } = require("ssh2");
+const { configDir } = require("./config");
 
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 
@@ -19,13 +22,49 @@ const ERR_PATTERNS = [
 ];
 
 // ssh2 默认算法集已兼容 JumpServer 常见旧算法（ssh-rsa hostkey、diffie-hellman-group14-sha1 等），
-// 无需额外放宽；hostVerifier 恒真等价于原 StrictHostKeyChecking=no。
+// 客户端列表强算法优先，无需额外放宽。
 const CONNECT_OPTIONS = {
   readyTimeout: 20000,
   keepaliveInterval: 10000,
-  hostVerifier: () => true,
 };
 
+// ==== 主机密钥 TOFU（trust-on-first-use）====
+// 等价并强于原 ssh -o StrictHostKeyChecking=no：首次连接记录堡垒机公钥指纹到
+// ~/.rrs/known_hosts.json，之后每次连接比对，不一致则拒绝（防中间人长期冒充）。
+
+function knownHostsPath(dir) {
+  return path.join(dir || configDir(), "known_hosts.json");
+}
+
+function loadKnownHosts(dir) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(knownHostsPath(dir), "utf8"));
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
+  } catch (_) {
+    return {};
+  }
+}
+
+function saveKnownHosts(store, dir) {
+  const target = knownHostsPath(dir);
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  fs.writeFileSync(target, JSON.stringify(store, null, 2), "utf8");
+}
+
+function hostKeyFingerprint(hostkey) {
+  return "sha256:" + crypto.createHash("sha256").update(hostkey).digest("base64");
+}
+
+/**
+ * 纯函数：比对主机密钥。首见返回 isNew=true（调用方负责持久化），
+ * 已知且匹配返回 ok=true；已知但不匹配返回 ok=false（应拒绝连接）。
+ */
+function checkHostKey(store, endpointId, hostkey) {
+  const fp = hostKeyFingerprint(hostkey);
+  if (!store[endpointId]) return { ok: true, fp, isNew: true };
+  return { ok: store[endpointId] === fp, fp, isNew: false, known: store[endpointId] };
+}
+
 /**
  * 从配置解析某目标主机所属的认证组（auth_profiles 条目）。
  * target_hosts[host] = { profile, keyword }；keyword 缺省回退为 host 本身。
@@ -58,6 +97,12 @@ function mapConnError(e) {
     /(password|passwd)[=:\s][^\s,;]+/gi,
     "$1=***"
   );
+  if (/host key verification|host denied/i.test(msg)) {
+    return new Error(
+      "堡垒机主机密钥与首次记录不一致（已拒绝，防中间人）。" +
+      "若堡垒机确实已更换，请删除 ~/.rrs/known_hosts.json 中对应条目后重试"
+    );
+  }
   if (/authentication|permission denied/i.test(msg)) {
     return new Error(`SSH 认证失败: ${msg}（请检查 auth_profiles 的账号/密码/私钥）`);
   }
@@ -72,12 +117,15 @@ function mapConnError(e) {
  * 仅负责"连接与收发"，命令校验在调用方（whitelist.js）完成。
  */
 class JumpShell {
-  constructor(conf, host) {
+  constructor(conf, host, opts = {}) {
     this.host = host;
     this.conf = conf;
     this.entry = resolveHostEntry(conf, host);
     this.profile = resolveProfile(conf, host);
     this.searchKeyword = this.entry.keyword || host;
+    // direct=true：跳过堡垒机菜单直连裸机（无 Opt> 流程）；命令只读校验链路不变
+    this.direct = this.profile.direct === true;
+    this.knownHostsDir = opts.knownHostsDir; // 测试注入用；缺省 ~/.rrs
     this.conn = null;
     this.stream = null;
     this.out = "";
@@ -96,11 +144,30 @@ class JumpShell {
     };
     if (p.auth.mode === "password") {
       cfg.password = p.auth.password;
+      // 兼容强制 keyboard-interactive 的堡垒机：用同一密码自动应答
+      cfg.tryKeyboard = true;
     } else {
       cfg.privateKey = fs.readFileSync(p.auth.private_key_path);
       if (p.auth.private_key_passphrase) cfg.passphrase = p.auth.private_key_passphrase;
     }
 
+    // 主机密钥 TOFU 校验：首见记录，不一致拒绝。
+    // ssh2 用户回调签名固定为 hostVerifier(key, verify)（key 为服务器公钥 Buffer）。
+    cfg.hostVerifier = (hostkey, verify) => {
+      try {
+        const store = loadKnownHosts(this.knownHostsDir);
+        const endpointId = `${cfg.host}:${cfg.port}`;
+        const r = checkHostKey(store, endpointId, hostkey);
+        if (r.isNew) {
+          store[endpointId] = r.fp;
+          saveKnownHosts(store, this.knownHostsDir);
+        }
+        verify(r.ok);
+      } catch (_) {
+        verify(false);
+      }
+    };
+
     return new Promise((resolve, reject) => {
       const conn = new Client();
       this.conn = conn;
@@ -109,6 +176,11 @@ class JumpShell {
         reject(mapConnError(e));
       };
       conn.on("error", fail);
+      if (p.auth.mode === "password") {
+        conn.on("keyboard-interactive", (_name, _instr, _lang, _prompts, finish) => {
+          try { finish([cfg.password || ""]); } catch (_) {}
+        });
+      }
       conn.on("ready", () => {
         conn.shell({ term: "xterm", rows: 30, cols: 120 }, (err, stream) => {
           if (err) return fail(err);
@@ -180,6 +252,12 @@ class JumpShell {
 
   async login(timeoutSecs = 30) {
     const deadline = Date.now() + timeoutSecs * 1000;
+    if (this.direct) {
+      // 直连模式：连上即 shell，只等 prompt；命令仍走白名单校验（whitelist.js）
+      if (!(await this.waitPrompt(deadline))) throw new Error("未能进入 shell（直连）");
+      await sleep(500);
+      return;
+    }
     if (!(await this.waitFor("Opt>", deadline))) throw new Error("跳板机菜单未出现");
     await sleep(1000);
     this.send("");
@@ -215,4 +293,8 @@ function cleanAnsi(t) {
     .replace(/\x1b\[[0-9;?]*[A-Za-z]/g, "");           // CSI 序列（颜色/光标）
 }
 
-module.exports = { JumpShell, cleanAnsi, sleep, PROMPT_RE, resolveHostEntry, resolveProfile, mapConnError };
+module.exports = {
+  JumpShell, cleanAnsi, sleep, PROMPT_RE,
+  resolveHostEntry, resolveProfile, mapConnError,
+  knownHostsPath, loadKnownHosts, saveKnownHosts, hostKeyFingerprint, checkHostKey,
+};