@zicolasjac-ai/remote-readonly-ssh 1.1.1 → 1.1.3

package/README.md

@@ -19,19 +19,28 @@ npm install -g @zicolasjac-ai/remote-readonly-ssh
 
 要求 Node.js >= 18，系统已装 OpenSSH 客户端（Windows 10+ / Linux / macOS 自带）。
 
+> **npx 一行命令**：`npx -y @zicolasjac-ai/remote-readonly-ssh init` 也可直接启动初始化向导（无需先 `npm install`）。
+>
 > 从旧包名 `remote-readonly-ssh`（v1.0.0）升级的用户，请先 `npm uninstall -g remote-readonly-ssh` 再安装，否则会报 `EEXIST: file already exists`。
 
+> **postinstall 自动引导**：全局安装完成后，TTY 环境下会自动进入初始化向导；非交互式安装（如 CI）会打印三行下一步提示，不会阻塞安装。
+
 ## 快速开始
 
 ```bash
-npm install -g @zicolasjac-ai/remote-readonly-ssh
-rrs init                 # 生成配置模板 ~/.rrs/config.json
-rrs setup skills         # 把 SKILL.md 安装到 opencode / claude / agents 等目录
-# 编辑配置: 填 jump_server / private_key_path / target_hosts
-rrs list-tools
-rrs sys-info --json
+npm install -g @zicolasjac-ai/remote-readonly-ssh   # 装完自动进向导
+# 或 npx -y @zicolasjac-ai/remote-readonly-ssh init
 ```
 
+向导会依次询问：
+
+1. 是否覆盖已有 `~/.rrs/config.json`（首次安装跳过此步）
+2. 堡垒机主机 / 端口 / 用户名 / SSH 私钥路径
+3. 目标主机白名单（每行 `ip=堡垒机搜索关键字`）
+4. 是否把 SKILL.md 安装到 opencode / Claude / Cursor 等 AI 助手
+
+向导非交互式环境（CI、管道）会静默生成配置模板，不阻塞安装。
+
 ## 用法
 
 ```
@@ -99,11 +108,20 @@ npm test          # 运行单元测试（node --test）
 ## 安全模型
 
 - **双层校验**：每条命令必须以允许前缀开头，且不得含禁止模式（rm/mv/vi/systemctl/sudo/重定向到文件/shadow/ssh 密钥等），否则一律拒绝。
-- **防绕过加固**：路径 `..` 穿越规范化、反斜杠转义、命令替换（`$()`、反引号）、分隔符（`;` `&` `&&`）等攻击面全部封堵。
+- **管道分段校验**：命令按 `|` 分段（引号内的 `|` 不分割），每个管道段都必须独立通过白名单——`... | sh`、`... | base64 -d` 等尾段注入全部拒绝。
+- **重定向白名单化**：仅放行 `2>&1` 形式的流重定向，`>`、`>>`、`>|`（强制覆盖）、`>&file` 等任何写文件形态一律拒绝。
+- **路径黑名单全局生效**：`exec-only` / `diff` / `find` 命令中出现的所有绝对路径（含规范化后的 `//x`、`/./x`、`/a/../b` 形态）都与 `read-file`/`dir` 受同一份 `blocked_paths` 约束。
+- **防绕过加固**：路径 `..` 穿越规范化、通配符 glob（`/etc/*/shadow`）、反斜杠转义、命令替换（`$()`、反引号）、变量展开（`$HOME`）、波浪号（`~`）、分隔符（`;` `&` `&&`）、换行注入等攻击面全部封堵；`hostname <name>`、`date -s` 等状态变更命令拒绝。
 - **参数防注入**：`proc`/`ports`/`bin-version` 参数做严格字符集校验。
 - **主机白名单**：未登记 IP 一律拒绝。
 - **无写原语**：工具集中不存在任何写操作路径；写操作由人工执行，本工具只读。
 
+**已知边界**（设计取舍）：
+
+- `--config` / 环境变量 `RRS_CONFIG` 可指向任意配置文件——本工具防护的是"AI 误发危险命令"，不防护对本地配置的恶意篡改（本地已有写权限的攻击者不在威胁模型内）。
+- `exec-only` 的相对路径参数（如 `cat file.txt`）不经过路径白名单（无法可靠区分文件名与普通参数）；家目录敏感文件已由禁词表（`.ssh`、`id_rsa`、`history` 等）与 `blocked_paths` 尽可能覆盖。
+- `exec-only` 中 `$`（含 grep 行尾锚 `'$'`）被整体禁用——需要正则锚的场景请用 `proc` 工具。
+
 ## 许可证
 
 MIT

package/bin/postinstall.js

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+"use strict";
+
+const initWizard = require("../src/init");
+const setupSkill = require("../src/setup");
+const path = require("path");
+
+const PACKAGE_ROOT = path.join(__dirname, "..");
+
+(async () => {
+  const tty = process.stdin.isTTY && process.stdout.isTTY;
+  if (tty) {
+    try {
+      await initWizard.runInteractive({ packageRoot: PACKAGE_ROOT });
+    } catch (e) {
+      console.error(`[rrs postinstall] 向导失败: ${e.message}`);
+      console.error("可稍后手动执行: rrs init");
+    }
+  } else {
+    console.log("");
+    console.log("rrs 安装完成。下一步:");
+    console.log("  rrs init                # 交互式初始化 + 安装 AI skill（推荐）");
+    console.log("  rrs setup skills        # 仅安装 AI skill 到 opencode / claude 等");
+    console.log("  rrs list-tools          # 查看白名单与配置");
+    console.log("");
+  }
+})();

package/bin/rrs.js

@@ -9,12 +9,13 @@ const {
   validateCmd, validatePath, validateHost, validateArg, validateBin,
 } = require("../src/whitelist");
 const setupSkill = require("../src/setup");
+const initWizard = require("../src/init");
 
 const PACKAGE_ROOT = path.join(__dirname, "..");
 
 function printUsage() {
   const cmds = [
-    ["init", "生成配置模板到 ~/.rrs/config.json"],
+    ["init", "交互式初始化向导（TTY 下）或生成配置模板"],
     ["list-tools", "查看工具、白名单、配置"],
     ["sys-info", "主机名/OS/内核/uptime"],
     ["proc <pattern>", "进程查询（防注入参数校验）"],
@@ -101,8 +102,10 @@ function runSetup(opts) {
 }
 
 function initConfig() {
+  if (process.stdin.isTTY && process.stdout.isTTY) {
+    return initWizard.runInteractive();
+  }
   const dir = configDir();
-  fs.mkdirSync(dir, { recursive: true });
   const dest = path.join(dir, "config.json");
   if (fs.existsSync(dest)) {
     console.log(`配置已存在: ${dest}（未覆盖，如需重置请手动删除）`);
@@ -218,4 +221,4 @@ if (require.main === module) {
   main();
 }
 
-module.exports = { parseArgs, buildCmds, printUsage, runSetup };
+module.exports = { parseArgs, buildCmds, printUsage, runSetup, initConfig };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zicolasjac-ai/remote-readonly-ssh",
-  "version": "1.1.1",
+  "version": "1.1.3",
   "description": "只读 SSH 运维 CLI 与 Agent Skill：通过 JumpServer 堡垒机白名单强制执行只读查询；附 SKILL.md 让 opencode / Claude Code / Cursor 等 AI 助手自动发现并正确调用。",
   "license": "MIT",
   "bin": {
@@ -36,6 +36,7 @@
   "dependencies": {},
   "scripts": {
     "test": "node --test",
+    "postinstall": "node bin/postinstall.js",
     "preuninstall": "node -e \"try { require('./src/setup').uninstall({agent:'all'}) } catch(_) {}\""
   }
 }

package/src/init.js

@@ -0,0 +1,142 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+const readline = require("node:readline/promises");
+const setupSkill = require("./setup");
+
+const PACKAGE_ROOT = path.join(__dirname, "..");
+
+function templatePath() {
+  return path.join(PACKAGE_ROOT, "config.example.json");
+}
+
+function readTemplate() {
+  return JSON.parse(fs.readFileSync(templatePath(), "utf8"));
+}
+
+function writeTemplate(destDir) {
+  fs.mkdirSync(destDir, { recursive: true });
+  const dest = path.join(destDir, "config.json");
+  if (fs.existsSync(dest)) return { dest, existed: true };
+  fs.writeFileSync(dest, JSON.stringify(readTemplate(), null, 2), "utf8");
+  return { dest, existed: false };
+}
+
+function parseTargets(text) {
+  const out = {};
+  for (const line of String(text || "").split(/\r?\n/)) {
+    const t = line.trim();
+    if (!t || t.startsWith("#")) continue;
+    const eq = t.indexOf("=");
+    if (eq <= 0) continue;
+    const ip = t.slice(0, eq).trim();
+    const kw = t.slice(eq + 1).trim();
+    if (ip && kw) out[ip] = kw;
+  }
+  return out;
+}
+
+function applyAnswers(cfg, answers) {
+  const a = answers || {};
+  if (a.jumpHost) cfg.jump_server.host = a.jumpHost;
+  if (a.jumpPort) cfg.jump_server.port = Number(a.jumpPort) || cfg.jump_server.port;
+  if (a.jumpUser) cfg.jump_server.username = a.jumpUser;
+  if (a.privateKeyPath) cfg.private_key_path = a.privateKeyPath;
+  if (a.targetHosts && Object.keys(a.targetHosts).length) cfg.target_hosts = a.targetHosts;
+  return cfg;
+}
+
+function defaultAnswersFor(cfg) {
+  return {
+    jumpHost: cfg.jump_server && cfg.jump_server.host ? "" : "",
+    jumpPort: cfg.jump_server && cfg.jump_server.port ? String(cfg.jump_server.port) : "22",
+    jumpUser: cfg.jump_server && cfg.jump_server.username ? cfg.jump_server.username : "",
+    privateKeyPath: cfg.private_key_path && !cfg.private_key_path.includes("YOURNAME") ? cfg.private_key_path : "",
+    targetHosts: cfg.target_hosts || {},
+  };
+}
+
+async function collectAnswers(rl, cfg, prompt) {
+  const ask = async (q, def) => {
+    const label = def ? `${q} [${def}]` : q;
+    const ans = (await rl.question(`${label}: `)).trim();
+    return ans || def || "";
+  };
+  const usePrompt = prompt && typeof prompt === "object";
+  const ans = {};
+  ans.jumpHost = usePrompt && prompt.jumpHost
+    ? await prompt.jumpHost(ask, cfg)
+    : await ask("堡垒机主机 IP / 域名", "");
+  if (!ans.jumpHost) {
+    throw new Error("跳过：未填写堡垒机主机。请稍后编辑 " + path.join(os.homedir(), ".rrs", "config.json"));
+  }
+  ans.jumpPort = usePrompt && prompt.jumpPort
+    ? await prompt.jumpPort(ask, cfg)
+    : await ask("堡垒机端口", "22");
+  ans.jumpUser = usePrompt && prompt.jumpUser
+    ? await prompt.jumpUser(ask, cfg)
+    : await ask("堡垒机用户名", "");
+  ans.privateKeyPath = usePrompt && prompt.privateKeyPath
+    ? await prompt.privateKeyPath(ask, cfg)
+    : await ask("SSH 私钥绝对路径", path.join(os.homedir(), ".ssh", "id_rsa"));
+  const targetText = usePrompt && prompt.targetHosts
+    ? await prompt.targetHosts(ask, cfg)
+    : await ask("目标主机（每行 ip=堡垒机搜索关键字，空行结束）", "");
+  ans.targetHosts = parseTargets(targetText);
+  return ans;
+}
+
+async function runInteractive({ input = process.stdin, output = process.stdout, packageRoot = PACKAGE_ROOT, prompt, installSkills = true, rlFactory } = {}) {
+  const destDir = path.join(os.homedir(), ".rrs");
+  const dest = path.join(destDir, "config.json");
+  const existed = fs.existsSync(dest);
+
+  const rl = rlFactory
+    ? rlFactory()
+    : readline.createInterface({ input, output });
+  try {
+    let overwrite = "n";
+    if (existed) {
+      const ans = (await rl.question(`检测到已存在配置 ${dest}\n  (n) 跳过配置，仅安装 skill  (b) 备份后重写  (y) 直接覆盖 [n]: `)).trim().toLowerCase();
+      overwrite = ans || "n";
+    }
+
+    if (!existed || overwrite === "y" || overwrite === "b") {
+      if (existed && overwrite === "b") {
+        fs.copyFileSync(dest, dest + ".bak");
+      }
+      fs.mkdirSync(destDir, { recursive: true });
+      const cfg = readTemplate();
+      const answers = await collectAnswers(rl, defaultAnswersFor(cfg), prompt);
+      const filled = applyAnswers(cfg, answers);
+      fs.writeFileSync(dest, JSON.stringify(filled, null, 2), "utf8");
+      output.write(`已写入配置: ${dest}\n`);
+    } else {
+      output.write(`保留现有配置: ${dest}\n`);
+    }
+
+    let installedSkills = false;
+    if (installSkills) {
+      const ans = (await rl.question("安装 AI skill 到 opencode / claude / agents 目录? [Y/n]: ")).trim().toLowerCase();
+      const install = ans || "y";
+      if (install !== "n") {
+        const results = setupSkill.install(packageRoot, { agent: "all" });
+        for (const r of results) {
+          output.write(`  [${r.agent}] ${r.action === "written" ? "已安装" : r.action} ${r.dir}\n`);
+        }
+        installedSkills = true;
+      }
+    }
+
+    output.write("\n下一步:\n");
+    output.write("  rrs list-tools           # 查看白名单与配置\n");
+    output.write("  rrs sys-info --json      # 试跑一次只读巡检\n");
+    return { dest, overwrite, installedSkills };
+  } finally {
+    if (!rlFactory) rl.close();
+  }
+}
+
+module.exports = { runInteractive, writeTemplate, readTemplate, parseTargets, applyAnswers, defaultAnswersFor, templatePath };

package/src/whitelist.js

@@ -18,35 +18,80 @@ const FORBIDDEN_PATTERNS = [
   /history/,
   // ---- anti-bypass hardening ----
   /\\/,                        // backslash escapes (r\m == rm)
-  /\$\(/,                      // command substitution
   /`/,                         // backtick substitution
-  /\$\{/,                      // parameter expansion (blocked to be safe)
   /;/,                         // command separator
   /(?<![>])&|&(?![0-9&])/,     // single & / && (allows only >&N redirect form)
   /\|\|/,                      // or operator
   /[\r\n]/,                    // embedded newline separators
+  /~/,                         // tilde expansion (== /root for root user)
+  /\$/,                        // variable expansion ($HOME etc; covers $( and ${ too)
+  /^hostname\s+\S/,            // hostname <name> sets the system hostname
+  /^date\s+(-s|--set)/,        // date --set changes the system clock
 ];
 
-const ARG_RE = /^[A-Za-z0-9._\-/:*]+$/;
+// 引号感知的管道分段：单双引号内的 | 不分割（grep -E 'a|b' 合法）
+function splitPipeline(cmd) {
+  const segs = [];
+  let cur = "";
+  let sq = false;
+  let dq = false;
+  for (const ch of cmd) {
+    if (ch === "'" && !dq) sq = !sq;
+    else if (ch === '"' && !sq) dq = !dq;
+    if (ch === "|" && !sq && !dq) { segs.push(cur); cur = ""; }
+    else cur += ch;
+  }
+  segs.push(cur);
+  return segs.map((s) => s.trim()).filter(Boolean);
+}
+
+// 提取命令中所有绝对路径 token（供 blocked_paths 黑名单核查）
+function extractAbsPaths(cmd) {
+  const out = [];
+  for (const m of cmd.matchAll(/(?:^|[\s'"])(\/[A-Za-z0-9._\-/]+)/g)) {
+    out.push(path.posix.normalize(m[1]));
+  }
+  return out;
+}
 
 function validateCmd(cmd, conf) {
   const c = String(cmd).trim();
   if (!c) throw new Error("空命令");
   if (/^(sudo |su )/.test(c)) throw new Error(`拒绝: 不允许提权命令 [${c}]`);
+  // 管道分段校验：每个管道段都必须独立通过白名单（防 "| sh"、"| base64 -d" 等尾段注入）
   const prefixes = conf.allowed_command_prefixes || [];
   const patterns = conf.allowed_command_patterns || [];
-  const okPrefix = prefixes.some((p) => c.startsWith(p));
-  const okPattern = patterns.some((p) => new RegExp(p).test(c));
-  if (!okPrefix && !okPattern) {
-    throw new Error(`拒绝: 命令不在白名单 [${c}]`);
+  for (const seg of splitPipeline(c)) {
+    const ok = prefixes.some((p) => seg.startsWith(p))
+      || patterns.some((p) => new RegExp(p).test(seg));
+    if (!ok) {
+      throw new Error(`拒绝: 命令段不在白名单 [${seg}]（整条: ${c}）`);
+    }
   }
   for (const pat of FORBIDDEN_PATTERNS) {
     if (pat.test(c)) throw new Error(`拒绝: 命中禁止模式 [${pat}] 命令 [${c}]`);
   }
+  // 重定向白名单化：剥离合法的 N>&M（如 2>&1）后，任何残留的 > 一律拒绝
+  // （覆盖 > file、>> file、>| 强制覆盖、>&file 等全部写文件形态）
+  const stripped = c.replace(/\d*>&\d+/g, "");
+  if (stripped.includes(">")) {
+    throw new Error(`拒绝: 命中禁止模式 [输出重定向] 命令 [${c}]`);
+  }
+  // 敏感路径核查：命令中出现的任何绝对路径都不得命中 blocked_paths
+  // （让 exec-only / diff / find 与 read-file/dir 受同一份路径黑名单约束）
+  const blocked = conf.blocked_paths || [];
+  for (const p of extractAbsPaths(c)) {
+    for (const sp of blocked) {
+      if (p.startsWith(sp) || `${p}/` === sp) {
+        throw new Error(`拒绝: 敏感路径 [${p}]（整条: ${c}）`);
+      }
+    }
+  }
   return c;
 }
 
-const PATH_RE = /^[A-Za-z0-9._\-/:*]+$/;
+const PATH_RE = /^[A-Za-z0-9._\-/:]+$/;  // 无通配符：glob 展开可绕过黑名单（/etc/*/shadow）
+const ARG_RE = /^[A-Za-z0-9._\-/:*]+$/;  // 参数允许 * （单引号内的 grep 正则量词，无注入面）
 
 function validatePath(pathArg, conf) {
   const raw = String(pathArg).trim();