jms-go

JumpServer 命令行客户端，编译为单个 Go 二进制。

jms-go 不调用外部 ssh CLI。它使用 golang.org/x/crypto/ssh 连接 JumpServer koko，通过个人 AccessKey 和 HTTP Signature 拉取授权资产，并在本地 profile 中缓存资产清单。

功能

• 公钥或平台密码认证；服务端要求时自动完成 TOTP MFA。
• 按资产名称、地址或备注匹配目标。
• 多匹配结果进入 Vim 风格 TUI。
• 通过 koko 直连用户名 平台用户@资产账号@资产地址 建立一跳连接。
• 交互 shell 和非交互命令执行。
• 多 profile 配置、资产缓存和 TOFU host key 隔离。
• API 不可用时继续使用已有缓存。

安装

需要 Go 1.25 或更高版本。

从模块安装：

go install github.com/chuandew/jms-go/cmd/jms-go@latest

私有仓库需要先配置 GitHub 凭据。也可以从源码构建：

git clone https://github.com/chuandew/jms-go.git
cd jms-go
make build
./build/jms-go --help

快速开始

jms-go init
# 编辑 ~/.jms-go/config.yaml
jms-go doctor
jms-go refresh
jms-go list
jms-go ssh web-prod

jms-go doctor 会检查：

1. 配置字段和第一因子认证材料。
2. TOTP 种子能否生成验证码；不会输出验证码。
3. AccessKey profile API；仅在同时配置 ID 和 secret 时执行。
4. 当前 profile 的资产缓存。
5. 到 koko 的 SSH 握手和认证。

命令

命令	行为
jms-go init	创建配置模板；已存在时拒绝覆盖
jms-go doctor	检查配置、认证、TOTP、API、缓存和 SSH
jms-go refresh	从 API 拉取全部授权资产并更新当前 profile 缓存
jms-go list [keyword]	列出缓存主机，可按名称、地址或备注过滤
jms-go ssh [account@]keyword	连接唯一匹配资产；多匹配时进入 TUI
jms-go exec [account@]keyword -- '<command>'	执行一个完整远程命令字符串并透传退出码
jms-go tui	打开资产选择器，再进入交互 shell
jms-go completion <shell>	生成 shell completion，不要求配置文件

通用旗标：

旗标	说明
--conf-dir <dir>	选择配置和运行状态目录，默认 ~/.jms-go
--no-input	禁止 TUI；多匹配时直接报错
--verbose, -v	输出配置警告

选择资产账号

优先级：

1. 命令行内联账号：root@web-prod。
2. 配置中的 default_account。
3. API 返回的唯一授权账号。
4. TUI 选择账号。

无 AccessKey 时无法查询账号列表，必须使用内联账号或 default_account。资产本身仍需存在于本地缓存。

执行远程命令

-- 后必须是一个完整命令字符串。外层单引号由本地 shell 负责保护命令内容：

jms-go exec web-prod -- 'df -h'
jms-go exec root@web-prod -- 'printf "%s\n" "a b"'
jms-go exec 10.0.0.10 -- 'uname -a && uptime'

不要拆成多个本地参数：

# 错误：会被参数校验拒绝
jms-go exec web-prod -- printf '%s\n' 'a b'

配置

默认配置文件为 ~/.jms-go/config.yaml：

server: jumpserver.example.com
api_scheme: https
ssh_port: 2222
username: your-jms-username
password: ""
otp_secret: BASE32TOTPSECRET
identity_file: ~/.ssh/id_ed25519
access_key_id: ""
access_key_secret: ""
default_account: ""
accept_new_host_key: true

字段	契约
server	JumpServer Web/koko 主机名或地址，不含 scheme
api_scheme	https 或显式要求的 http，默认 https
ssh_port	koko SSH 端口，默认 2222
username	JumpServer 平台用户名
identity_file	明确指定的私钥；配置后只加载这一把
password	平台密码；可替代私钥，也可与私钥同时配置
otp_secret	Base32 TOTP 种子；MFA 服务端启用时需要
access_key_id	个人 AccessKey ID
access_key_secret	个人 AccessKey secret
default_account	多账号资产的默认资产账号
accept_new_host_key	是否对未知 koko host key 使用 TOFU

至少配置 identity_file 或 password。当前版本不支持加密私钥和 SSH agent；显式私钥读取或解析失败会直接报错，不会回退到默认密钥。

MFA 只自动回答已识别的 JumpServer 方法选择和验证码提示。未知 keyboard-interactive 问题会终止认证，不会自动确认。

Profile 隔离

通过 --conf-dir 使用独立环境：

jms-go --conf-dir ~/.jms-go-prod init
jms-go --conf-dir ~/.jms-go-prod doctor
jms-go --conf-dir ~/.jms-go-prod refresh

每个 profile 独立保存：

文件	用途
<conf-dir>/config.yaml	配置和凭据
<conf-dir>/assets.json	授权资产缓存
<conf-dir>/known_hosts	jms-go 接受的 koko host key

SSH 校验同时读取标准 ~/.ssh/known_hosts。新 host key 只写入当前 profile 的 known_hosts。

资产缓存

• 缓存超过 24 小时或为空时，连接命令会尝试自动刷新。
• keyword 未命中时会再刷新一次，然后重新匹配。
• API 刷新失败时保留并使用旧缓存。
• jms-go refresh 强制刷新。
• 缓存文件权限为 0600。

资产 cache 只包含授权资产快照，不包含 AccessKey；仍应按内部资产信息保护。

Host key 策略

accept_new_host_key: true 使用 TOFU：

1. 先检查 ~/.ssh/known_hosts 和当前 profile 的 known_hosts。
2. 未知 key 首次接受并写入 profile。
3. 已记录主机发生 key mismatch 时拒绝连接。

高安全环境应预置 koko host key，并设置：

accept_new_host_key: false

安全边界

config.yaml 可能同时包含平台密码、TOTP 种子和 AccessKey，等同完整平台凭据：

• jms-go init 以 0600 创建配置；手工创建时必须保持相同权限。
• 不要提交到 Git、同步盘、日志或工单。
• jms-go doctor 只报告 TOTP 生成成功，不输出当前验证码。
• 泄露后应立即重绑 MFA、作废 AccessKey，并在使用密码认证时修改平台密码。
• exec 有意把完整字符串交给远端 shell；只执行可信输入。

代码结构

路径	职责
cmd/jms-go/	进程入口
internal/commands/	Cobra 命令和业务编排
internal/config/	profile 配置读写与校验
internal/assets/	profile-local 资产缓存
internal/jmsapi/	AccessKey HTTP Signature REST 客户端
internal/sshc/	SSH 认证、MFA、host key、PTY 和 exec
internal/otp/	RFC 6238 TOTP
internal/tui/	Bubble Tea 资产选择器

开发与验证

make fmt
make test
make vet
make build
go test -race ./...

仓库测试覆盖：

• RFC 6238 TOTP 向量和 secret 规范化。
• 自定义配置目录和文件权限。
• 多 profile 资产缓存隔离。
• 显式私钥、password-only 和 MFA prompt allowlist。
• profile-local known_hosts。
• completion 配置豁免和 exec 单字符串契约。

自动测试不连接真实 JumpServer。发布或部署前应在目标环境依次运行 jms-go doctor、jms-go refresh、jms-go list、jms-go exec 和 jms-go ssh。