JumpServer Skills

jumpserver-skills 是一个面向 JumpServer V3.10 LTS（含企业版 XPack）的查询、审计分析与模板化使用报告工具仓库，适用于对象查询、权限回看、审计调查、治理巡检、访问分析，以及某一天或某一段时间的堡垒机使用报告。它提供可复用的规则文档与正式 CLI 入口封装，而不是要求使用者手动拼接 HTTP 请求。

仓库内部按请求类型路由到 jms_query.py、jms_diagnose.py、jms_report.py 三类正式入口。默认保持只读，仅允许本地运行时写入 .env 和当前组织上下文，不执行 JumpServer 业务写操作。

当前结构为“1 个总路由 + 7 个按业务场景拆分的子模块 + 共享运行时”，可按场景单独注册或整体使用。

English

最快上手

1. 在仓库根目录准备 .env（可复制 .env.example 后修改）。
2. 执行预检：python jumpserver-runtime-setup/scripts/jms_diagnose.py config-status --json，然后 ping。
3. 按需调用查询、诊断或报告入口，例如查网域列表、查用户有效资产、生成使用报告。

企业版环境建议额外验证许可证：python jumpserver-governance-inspection/scripts/jms_diagnose.py license-detail。

这个仓库能做什么

能力分组	适合处理的请求	入口名称	说明
对象查询	资产、账号、用户、用户组、组织、平台、节点、标签、网域查询	jms_query.py	精确查询对象清单或读取单个对象详情；网域路径 /api/v1/assets/domains/
权限关系	授权规则、ACL、RBAC、资产授权给了谁、谁能访问某资产、某条权限详情	jms_query.py / jms_diagnose.py	默认区分“授权主体”和“实际可访问者”
审计调查	登录、会话、命令、文件传输、异常行为、高危命令、失败登录调查	jms_query.py	日志、记录、明细类请求
配置与诊断	配置检查、连通性、组织切换、对象解析、许可证、系统设置、存储、工单	jms_diagnose.py	预检、环境确认和治理前置检查
用户有效访问范围	某用户有哪些资产/节点/账号/协议	jms_diagnose.py	优先返回 effective access 结果
治理巡检	资产治理、账号治理、访问分析、系统巡检、capability 聚合	jms_diagnose.py	走能力化聚合，支持 XPack 许可证查询
使用报告	日报、使用情况、某天发生了什么、某时间段排行或概览	jms_report.py	默认输出完整 HTML 报告

子模块结构

子模块	负责场景	主要入口
jumpserver-runtime-setup	配置、预检、连通性、组织切换、排障	jms_diagnose.py
jumpserver-object-query	资产、账号、用户、组织、平台、节点、标签、网域	jms_query.py
jumpserver-effective-access	用户实际可访问的资产、节点、账号、协议	jms_diagnose.py
jumpserver-permission-analysis	授权规则、ACL、RBAC、访问原因分析	jms_query.py / jms_diagnose.py
jumpserver-audit-investigation	登录、会话、命令、文件传输、作业审计	jms_query.py / jms_diagnose.py
jumpserver-usage-reporting	使用情况、排行、概览、HTML 报告	jms_report.py
jumpserver-governance-inspection	治理巡检、系统设置、许可证、工单、存储	jms_diagnose.py

共享底层位于 jumpserver-api/。每个子模块提供 scripts/*.py 本地入口。若运行环境一次只能注册一个模块，可直接使用某个 jumpserver-* 目录，详见 references/single-skill-registration.md。

怎么使用

1. 准备环境文件

cp .env.example .env
# 编辑 JMS_API_URL、认证方式、组织等

也可通过正式入口写入配置：

python jumpserver-runtime-setup/scripts/jms_diagnose.py config-write \
  --payload '{"JMS_API_URL":"http://10.1.14.82","JMS_USERNAME":"admin","JMS_PASSWORD":"***"}' \
  --confirm

2. 执行预检

python jumpserver-runtime-setup/scripts/jms_diagnose.py config-status --json
python jumpserver-runtime-setup/scripts/jms_diagnose.py ping
python jumpserver-runtime-setup/scripts/jms_diagnose.py select-org --org-name Default

3. 按场景调用正式入口，不需要手工拼 HTTP 请求。

4. 根据返回结果补充参数。若出现 candidate_orgs、switchable_orgs 或缺少时间范围，按 user_message / action_hint / suggested_commands 继续。

手工 CLI 路径

推荐写法：

python jumpserver-runtime-setup/scripts/jms_diagnose.py select-org --org-name Default
python jumpserver-effective-access/scripts/jms_diagnose.py user-assets --org-name Default --username admin
python jumpserver-object-query/scripts/jms_query.py object-list --resource organization --name Default
python jumpserver-object-query/scripts/jms_query.py object-list --resource domain
python jumpserver-audit-investigation/scripts/jms_query.py audit-analyze --capability session-record-query --days 7 --user admin
python jumpserver-governance-inspection/scripts/jms_diagnose.py inspect --capability hot-assets-ranking --days 30 --top 10
python jumpserver-governance-inspection/scripts/jms_diagnose.py license-detail

列表型和分析型命令会自动翻页，不再支持 --limit/--offset。

环境变量

变量	是否必需	说明
JMS_API_URL	必需	JumpServer API 地址
JMS_ACCESS_KEY_ID / JMS_ACCESS_KEY_SECRET	与用户名密码二选一	API Access Key
JMS_USERNAME / JMS_PASSWORD	与 AK/SK 二选一	登录用户名密码
JMS_ORG_ID	可选	组织 ID，可通过 select-org 写入
JMS_TIMEOUT	可选	请求超时秒数
JMS_VERIFY_TLS	可选	是否校验证书，默认 false

规则：

• 必须提供 JMS_API_URL 和一组完整认证信息。
• .env 由运行时自动加载；切换环境或账号后应重新预检。

典型场景

• 查询 Demo-User 用户详情
• 查看 Demo-Node 节点下有哪些资产
• 查看 Linux 平台下可用资产
• 查询某用户在 Default 组织下有哪些资产
• 查看授权规则详情及影响的用户/资产
• 查询某资产授权给了谁
• 查询最近一周登录审计
• 查看用户会话记录与异常中断
• 排查昨天的高危命令与文件传输审计
• 生成某天或某时间段的使用报告

边界说明：

• “某用户有哪些资产/节点/账号” → 用户有效访问范围，优先 user-assets / user-nodes
• “为什么能访问 / 授权规则详情” → 权限关系分析
• “某天登录情况 / 排行 / TOP” → 使用报告
• “某天登录日志 / 命令记录 / 会话详情” → 审计调查

使用报告与时间范围

涉及某一天或某一段时间的使用数据分析时，优先走 HTML 模板报告流程。

日期表达会先归一化为 --date、--period 或 --date-from/--date-to：

• 昨天 / 2026-03-10 / 3月10号 → 单日 00:00:00 ~ 23:59:59
• 上周 → 上一自然周周一至周日
• 2026-03-10 到 2026-03-24 → 明确起止时间窗

报告输出到 reports/JumpServer-YYYY-MM-DD.html。

组织选择与阻塞规则

• 用户指定组织时按指定组织执行；user-assets 等命令可用 --org-name 临时限定，不写回 .env。
• 报告类请求未指定组织时，可尝试全局组织 00000000-0000-0000-0000-000000000000。
• 组织无法自动确定时返回 candidate_orgs，必须先选择再继续。
• 配置不完整、对象重名、跨组织等情况会先阻塞，不猜测执行。

文档地图

文件	用途
SKILL.md	总路由规则、组织优先级与响应约束
references/api-reference.md	V3.10 LTS API 路径与企业版 XPack 说明
references/single-skill-registration.md	单模块注册方式
references/routing-playbook.md	路由、触发词、阻塞规则
references/report-template-playbook.md	模板报告流程与时间范围
references/runtime.md	预检、环境变量、组织选择
references/capabilities.md	capability 能力目录
references/assets.md	对象查询说明
references/permissions.md	权限与授权关系
references/audit.md	审计说明
references/diagnose.md	诊断与治理巡检
references/safety-rules.md	查询边界与阻塞规则
references/troubleshooting.md	常见错误排查
DEVELOPMENT.md	开发与扩展指南

不支持范围

• 资产、用户、组织、权限等的创建、更新、删除。
• 跳过预检直接执行业务写操作。
• 临时 HTTP/SDK 脚本绕过正式入口。
• 对象或组织不明确时继续猜测执行。