# python_jms_clienter

一个面向 JumpServer 的 Python 客户端，支持以下三种使用方式：

- 作为 Python 模块导入
- 作为 CLI 命令执行（可直接输出 JSON）
- 作为 TUI 交互程序执行（服务器和用户名均通过选择，不需要手工输入）

---

## 中文说明

### 1) 项目定位

`python_jms_clienter` 是一个**第三方客户端工具**，用于通过 JumpServer OpenAPI 获取连接 token，支持数据库（不限 MySQL）和 SSH 主机场景。

### 2) 与 JumpServer 项目的关系

请注意以下边界：

1. 本项目**不是 JumpServer 官方项目**，也不是 JumpServer 服务端的插件。  
2. 本项目仅调用 JumpServer 暴露的 OpenAPI 接口，不包含 JumpServer 服务端实现代码。  
3. 本项目需要你已经部署并可访问 JumpServer 实例，且有可用的 Access Key（`key_id` / `key_secret`）。  
4. 本项目 API 字段与流程参考仓库内 `doc/api/less.json`（JumpServer OpenAPI 导出），不同 JumpServer 版本可能存在差异。  
5. `JumpServer` 名称与商标归原项目及其权利方所有，本项目仅做兼容调用。  

### 3) 当前实现的能力

- 列出可用服务器（支持数据库与 SSH）
- 按服务器列出可选用户名
  - 默认输出“可连接账号”对应用户名（会做 token 探测）
  - 可用 `--raw` 查看 JumpServer `username-suggestions` 原始结果
- 基于 `asset + account` 申请连接 token
- `get-token` 默认输出精简字段（自动识别 SSH/数据库连接方式）：
  - `token_username = token.id`
  - `token_password = token.value`

### 4) 使用到的关键接口

- `GET /api/v1/assets/assets/suggestions/`
- `GET /api/v1/assets/databases/suggestions/`
- `GET /api/v1/assets/hosts/suggestions/`（以及设备/网关等 suggestions 端点）
- `POST /api/v1/accounts/accounts/username-suggestions/`
- `POST /api/v1/authentication/connection-token/`

鉴权方式：`Authorization: Signature ...`（HMAC-SHA256）

### 5) 安装

先安装依赖：

```bash
pip install -r requirements.txt
```

开发模式安装（会注册 `jms-client` 命令）：

```bash
pip install -e .
```

### 6) 环境变量

```bash
export JMS_BASE_URL="https://jumpserver.example.com"
export JMS_KEY_ID="your-access-key-id"
export JMS_KEY_SECRET="your-access-key-secret"
export JMS_ORG_ID="00000000-0000-0000-0000-000000000002"   # 可选
export JMS_VERIFY_SSL="true"                                   # 可选，false 表示跳过证书校验
export JMS_TIMEOUT="15"                                        # 可选，单位秒
export JMS_DEBUG="true"                                        # 可选，开启调试日志
export JMS_LOG_FILE="./jms-client.debug.log"                   # 可选，写入日志文件
```

### 7) CLI 用法

无子命令时默认进入 TUI：

```bash
jms-client
```

也可以通过项目根目录入口执行（`main.py` 会提供 TUI/CLI 模式选择）：

```bash
python main.py
```

直接指定模式：

```bash
python main.py tui --base-url https://jumpserver.example.com --key-id <id> --key-secret <secret>
python main.py tui
python main.py cli list-servers
python main.py tui --debug --log-file ./jms-debug.log
python main.py debug tui
python main.py debug cli list-servers
```

列服务器：

```bash
jms-client list-servers --type mysql --category database --limit 200
jms-client list-servers --protocols ssh --category "" --type "" --limit 200
```

按服务器 ID 列用户名：

```bash
jms-client list-usernames --asset-id 15d0eccb-e3dd-426f-a117-43e44520a4ac
```

按服务器名列用户名（默认仅可连接用户名）：

```bash
jms-client list-usernames --asset-name UAT-EMQX-Mysql
```

查看原始 suggestions（不做可连接性探测）：

```bash
jms-client list-usernames --asset-name UAT-EMQX-Mysql --raw
```

获取 token（指定服务器 ID + 用户名）：

```bash
jms-client get-token \
  --asset-id 15d0eccb-e3dd-426f-a117-43e44520a4ac \
  --account root-readonly \
  --connect-method db_guide
```

说明：`get-token` 默认返回精简 token 字段；如需完整原始 token，增加 `--full-token`。
说明：若不指定 `--connect-method`，CLI 会自动识别：
- SSH 主机优先 `ssh_guide + ssh`
- 数据库资产优先 `db_guide + <db protocol>`

获取 token（按服务器名自动解析）：

```bash
jms-client get-token --asset-name mysql-prod-a --account root-readonly
```

开启调试日志（建议排障时使用）：

```bash
jms-client --debug --log-file ./jms-debug.log get-token --asset-id <id> --account <account>
```

说明：调试日志会自动对敏感字段（例如 `key-secret`、`Authorization`、token 值）做脱敏处理。

CLI 所有子命令均返回 JSON，方便脚本直接消费。

### 8) TUI 用法

TUI 中：

- 第一步选择服务器（数据库 + SSH）
- 第二步选择账号（仅展示该机器存在且当前用户可连接的账号）
- 第三步申请 token 并显示精简 JSON 结果（字段与 CLI `get-token` 默认输出一致）
- 如果未提供 `base-url / key-id / key-secret`（参数或环境变量），启动时会先友好提示输入（`key-secret` 为隐藏输入）

按键：

- `Up/Down` 移动
- `PgUp/PgDn` 翻页
- `p/n` 翻页（终端不识别 `PgUp/PgDn` 时可用）
- `Space/b` 翻页（`Space` 下一页，`b` 上一页）
- `j/k` 移动（Vim 风格）
- `/` 搜索（输入关键字过滤当前列表）
  - 输入后会自动远程补拉匹配服务器（不仅是本地已加载列表）
- `c` 清除搜索过滤
- `Enter` 选择
- `q` / `Esc` 退出

### 9) 模块导入用法

推荐使用环境变量方式（避免在代码中写死密钥）：

```python
from python_jms_clienter import JMSClient

client = JMSClient.from_env(base_url="https://jumpserver.example.com")
# 也可完全从环境变量读取（包含 JMS_BASE_URL）:
# client = JMSClient.from_env()
# 开启调试日志:
# client = JMSClient.from_env(debug=True, log_file="./jms-debug.log")

servers = client.list_servers(asset_type="mysql", category="database")
ssh_servers = client.list_servers(protocols="ssh", category=None, asset_type=None)
print(servers)
print(ssh_servers)

asset_id = servers[0]["id"]
usernames = client.list_usernames(asset_id)
print(usernames)

token = client.get_connection_token(asset_id=asset_id, account=usernames[0])
print(token)

mysql_credentials = {
    "username": token["id"],
    "password": token["value"],
}
print(mysql_credentials)
```

如果你仍然希望显式传参，也支持：

```python
client = JMSClient(
    base_url="https://jumpserver.example.com",
    key_id="your-access-key-id",
    key_secret="your-access-key-secret",
)
```

### 10) 安全与合规建议

- 不要把 `key_secret` 写入代码仓库，优先使用环境变量或密钥管理系统。
- 生产环境不要使用 `--insecure` / `JMS_VERIFY_SSL=false`。
- 建议为此客户端申请最小权限 API Key，仅授予必要资源范围。

### 11) 许可证

本项目使用 **GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later)**。

完整文本见 [LICENSE](./LICENSE)。

---

## English Summary

### Scope

`python_jms_clienter` is a **third-party client** for JumpServer OpenAPI, supporting token generation for both MySQL and SSH workflows.

### Relationship to JumpServer

- This repository is **not an official JumpServer repository**.
- It only calls JumpServer OpenAPI endpoints and does not include JumpServer server-side implementation.
- You must provide your own JumpServer deployment and valid access keys.
- API behavior may vary across JumpServer versions; this client is based on the OpenAPI snapshot in `doc/api/less.json`.

### Features

- List servers
- List usernames for a selected server
- Create connection token
- Run as module / CLI / TUI
- JSON output for CLI automation

### License

This project is licensed under **AGPL-3.0-or-later**. See [LICENSE](./LICENSE).