rrs

CLI and Agent Skill for safe read-only SSH inspection via JumpServer.

让 AI 助手（opencode / Claude Code / Cursor / Windsurf / Codex 等）通过堡垒机白名单强制地在服务器上做只读查询——技术上零写能力，每次调用（含被拒绝的）写入本地审计日志。

为什么需要它

• 技术强制只读：命令前缀白名单 + 禁止模式 + 参数防注入 + 目标主机白名单，多层校验。
• 审计留痕：每次调用（含被拒绝的记录）写入本地审计日志，可随时审查。
• 零依赖：只依赖系统自带 ssh 客户端，无 npm 依赖树。
• AI Agent 友好：附带 SKILL.md 可一键安装到 opencode / Claude / Cursor / Windsurf / Codex / OpenHands 等 AI 助手的 skills 目录。

开始使用

一行命令搞定（推荐）：

npx -y @zicolasjac-ai/remote-readonly-ssh@latest init

npx 会自动拉取最新版本、进入初始化向导，依次询问：

1. 是否覆盖已有 ~/.rrs/config.json（首次安装跳过此步）
2. 堡垒机主机 / 端口 / 用户名 / SSH 私钥路径
3. 目标主机白名单（每行 ip=堡垒机搜索关键字）
4. 是否把 SKILL.md 安装到 opencode / Claude Code / Cursor 等 AI 助手

向导结束后 ~/.rrs/config.json 已就位、~/.rrs/audit.log 已建好、AI skill 已分发。直接试跑：

npx -y @zicolasjac-ai/remote-readonly-ssh@latest sys-info --json

反复使用？装到全局

每次调用都 npx 较慢（需下载/缓存）。如果要把 rrs 作为日常命令长期使用：

npm install -g @zicolasjac-ai/remote-readonly-ssh
rrs init                # TTY 下仍是交互向导；非交互环境只生成配置模板
rrs sys-info --json     # 直接用 rrs 前缀

postinstall 自动引导：npm install -g 完成后，TTY 环境会自动进入向导；非交互环境（如 CI）只打印三行下一步提示，不阻塞安装。

从旧包名 remote-readonly-ssh（v1.0.0）升级的用户，请先 npm uninstall -g remote-readonly-ssh 再安装，否则会报 EEXIST: file already exists。

要求 Node.js >= 18，系统已装 OpenSSH 客户端（Windows 10+ / Linux / macOS 自带）。

用法

rrs <tool> [arg] [--host <ip>] [--config <file>] [--json]

--json 以 JSON 输出结果（{"ok":true,"tool":...,"host":...,"output":...}），便于脚本/AI 调用；-v / --version 查看版本。

| 工具 | 说明 | |------|------| | init | 启动初始化向导（TTY 交互） / 静默生成配置模板（非 TTY） | | list-tools | 查看工具、白名单、配置路径 | | sys-info | 主机名 / 系统版本 / 内核 / 运行时间 | | proc <pattern> | 进程查询（严格字符校验，防注入） | | ports [filter] | 监听端口查询（ss -tln） | | read-file <path> | 读文件（路径白名单 + 敏感黑名单） | | dir <path> | 列目录（同路径白名单） | | bin-version <bin> | 查二进制版本/编译参数（二进制白名单） | | exec-only <cmd> | 通用只读命令（前缀白名单 + 禁止模式） |

配置

文件：~/.rrs/config.json（可用 --config <file> 或环境变量 RRS_CONFIG 覆盖）

| 键 | 说明 | |-----|------| | 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 的二进制白名单 | | allowed_command_prefixes | 只读命令前缀白名单（cat/ls/grep/ps/ss/tail...） | | allowed_path_prefixes | 允许读取的路径前缀 | | blocked_paths | 敏感路径黑名单（shadow/passwd/密钥/家目录） |

审计日志：~/.rrs/audit.log

Agent Skills

本工具附带一份 SKILL.md，教 AI 助手何时用、怎么用 rrs。安装后用 rrs setup skills 一键分发到各 agent 的 skills 目录：

| --agent | 写入方式 | 路径 | |-----------|----------|------| | agents（canonical） | 实体文件 | ~/.agents/skills/remote-readonly-ssh/SKILL.md | | opencode | 软链接 → agents | ~/.config/opencode/skills/remote-readonly-ssh/SKILL.md | | claude / claudecode / cursor / windsurf / codex | 软链接 → agents | ~/.claude/skills/remote-readonly-ssh/SKILL.md | | qoder | 软链接 → agents | ~/.qoder/skills/remote-readonly-ssh/SKILL.md | | all（默认） | 实体 + 上述 3 个软链接 | 一行命令装齐 |

rrs setup skills 默认 agent=all（不询问，直接装），输出一行简明提示：

rrs skill 已安装: agents (实体), opencode/claude/qoder (软链接)

Windows 注意：普通用户缺少 SeCreateSymbolicLinkPrivilege，软链接创建会被 OS 拒绝；rrs 会自动 fallback 为复制，并提示"Windows 已 fallback 为复制（请开启开发者模式以启用真软链接）"。开启开发者模式后重新跑 rrs setup skills 即可使用真软链接。

rrs setup skills                            # 一行命令装齐（实体 + 3 个软链接）
npx -y @zicolasjac-ai/remote-readonly-ssh@latest setup skills   # 全局未装时用 npx
rrs setup skills --agent opencode           # 只装 opencode 链接（agents 实体也自动建）
rrs setup skills --agent qoder              # 只装 qoder 链接
rrs setup skills --dry-run                  # 仅预览将要创建的目标
rrs setup uninstall skills                    # 全部移除（实体 + 软链接）

卸载 npm 包时会自动尝试清理这些 skill 文件（preuninstall 钩子，失败不影响卸载）。

开发

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