JumpServer CLI-Anything：面向 AI Agent 与运维人员的堡垒机命令行工具全解析

JumpServer CLI-Anything面向 AI Agent 与运维人员的堡垒机命令行工具全解析【免费下载链接】CLI-AnythingCLI-Anything: Making ALL Software Agent-Native -- CLI-Hub: https://clianything.cc/项目地址: https://gitcode.com/GitHub_Trending/cl/CLI-AnythingJumpServer是开源领域广泛使用的特权访问管理PAM/堡垒机平台而本仓库中的jumpserver/agent-harness子项目为其打造了一套无状态与有状态兼备的命令行 Harness它把堡垒机的资产、用户、权限、账号、会话、审计、系统运维等 REST API 能力封装为统一 CLI既能被人直接在终端使用也能被 AI Agent 以表格/JSON 形式程序化消费。本篇文章以 jumpserver/agent-harness/cli_anything/jumpserver/README.md 为主干结合源码与测试展开读完你将掌握如何安装配置该 CLI、其命令体系与输出格式设计、底层会话/状态持久化与安全机制以及如何为 JumpServer 实例跑通单元测试与端到端测试。项目定位与整体架构cli-anything-jumpserver是一个有状态stateful的 JumpServer 命令行工具包状态之所以重要是因为堡垒机日常操作通常需要先登录、再在多组织、多资产、多筛选条件下反复执行操作。它同时支持一次性命令与交互式 REPL两种模式并统一提供 table / json / yaml 三种输出。从目录结构看Harness 采用 PEP 420 命名空间包组织外层cli_anything无__init__.py内层子包jumpserver有__init__.py安装入口与命令分组清晰分离jumpserver/agent-harness/ ├── JUMPSERVER.md # 标准操作流程文档SOP ├── setup.py # PyPI 打包配置 └── cli_anything/jumpserver/ # 子包含 __init__.py ├── __init__.py # 包元数据__version__ 0.1.0 ├── jumpserver_cli.py # Click 主入口 REPL 实现 ├── core/ │ ├── session.py # Session JumpServerClientHTTP 客户端 │ ├── state.py # CLIState 操作状态管理 │ ├── output.py # table/json/yaml 格式化 │ ├── commands_auth.py # auth 认证命令组 │ ├── commands_asset.py # asset 资产命令组 │ ├── commands_user.py # user 用户命令组 │ ├── commands_perm.py # perm 授权命令组 │ ├── commands_account.py# account 账号命令组 │ ├── commands_session.py# session 会话命令组 │ ├── commands_audit.py # audit ops 审计与运维组 │ └── commands_system.py # system label role 组 ├── utils/__init__.py # 工具函数、CLIError、脱敏逻辑 ├── skills/SKILL.md # 随包分发的技能描述 └── tests/ # test_core.py(单测) test_full_e2e.py(E2E)主入口 jumpserver_cli.py 基于 Click 构建了一个自定义JumpserverCLI(click.Group)一次性注册 11 个命令组auth、asset、user、perm、account、session、audit、ops、system、label、role同时支持--json、--json-output、--interactive等全局选项以及通过python -m cli_anything.jumpserver直接运行。快速开始安装、配置与连接测试安装前提根据 README.md 与 setup.py需要满足Python 3.10README 要求setup.py 中python_requires3.11实际以打包元数据为准一个JumpServer v3.0实例且 API 可访问一个JumpServer Private Token——README 明确指出它通过 Django shell 生成u.create_private_token()。安装方式在仓库根目录定位到 harness 子目录后通过 pip 安装等价于pip install .cd jumpserver/agent-harness pip install .安装成功后setup.py注册的 console_scripts 入口cli-anything-jumpserver即可用它指向cli_anything.jumpserver.jumpserver_cli:cli_main。也可以不走安装、直接以模块方式运行python -m cli_anything.jumpserver --help运行依赖为click8.0、requests2.28、pyyaml6.0见 setup.py。配置与测试连接README 给出的标准配置流程一次性命令、适合脚本与 Agent 场景# Configure cli-anything-jumpserver config set base_url https://jumpserver.example.com cli-anything-jumpserver config set token YOUR_PRIVATE_TOKEN # Test connection cli-anything-jumpserver config test # Start using cli-anything-jumpserver asset list cli-anything-jumpserver --interactive在此基础上源码进一步揭示了这套机制的底层实现session.py 中的Session数据类把连接状态持久化到~/.jumpserver-cli/session.json而每次请求时 JumpServerClient 会在请求头中携带Authorization: Token token并在设置了组织时附加X-JMS-ORG头这正是 JumpServer v3 多组织场景下必需的请求头。因此配置一次、随处使用的本质就是把会话 JSON 落盘并自动加载。账号密码登录替代方式若不方便预生成 Private TokenCLI 还提供了基于账号密码的auth login流程见 commands_auth.py并支持环境变量注入避免密码出现在 shell 历史中cli-anything-jumpserver auth login \ --url https://jumpserver.example.com \ --username admin \ --password YOUR_PASSWORD # 或用环境变量 JUMPSERVER_URLhttps://jumpserver.example.com \ JUMPSERVER_USERNAMEadmin \ JUMPSERVER_PASSWORDxxx \ cli-anything-jumpserver auth login --url $JUMPSERVER_URL --username $JUMPSERVER_USERNAME --password $JUMPSERVER_PASSWORDauth login成功后会把 token、用户名、过期时间写回会话文件auth logout清除会话auth status查看当前认证状态与 token 剩余有效期auth org --list可列出/切换多组织。这里 token 默认有效期 1 小时time.time() 3600见 session.py过期后is_authenticated()返回 False需要重新登录。命令体系从资产管理到审计运维README 将功能归纳为七大类源码则将其落实为 11 个 Click 命令组。下表汇总各命令组、对应 JumpServer API 资源与其承担的职责详见 JUMPSERVER.mdCLI 命令组对应 API 端点功能auth/api/v1/authentication/登录/登出/状态/组织切换asset/api/v1/assets/资产 CRUD、节点、平台、网关、区域user/api/v1/users/用户/用户组管理、个人资料、我的资产perm/api/v1/perms/资产授权规则account/api/v1/accounts/账号凭据、密钥、模板session/api/v1/terminal/会话监控、回放、终端状态audit/api/v1/audits/登录/操作/FTP/改密审计日志ops/api/v1/ops/作业执行、Playbook、临时命令system/api/v1/settings/系统设置与健康检查label/api/v1/labels/标签管理role/api/v1/rbac/角色与绑定管理资产管理asset资产管理是堡垒机使用频率最高的部分。以asset list为例它支持--type限定资产子类型并映射到不同 REST 端点host→hosts、device→devices、database→databases、web→webs、cloud→clouds、gpt→gpts、ds→directories、custom→customs见 commands_asset.py并支持--search、--node、--platform、--active/--inactive及--limit/--offset分页cli-anything-jumpserver asset list --type host --search 10.0.0. cli-anything-jumpserver asset list --type database --limit 50 cli-anything-jumpserver asset node list --tree # 查看树形节点 cli-anything-jumpserver asset gateway list cli-anything-jumpserver asset zone list新建资产时需要--name、--address、--platform平台 ID可选--nodes、--comment、--active/--inactive所有变更类命令均支持--dry-run先行预览见下文Dry Run 安全模式。此外asset node add-assets、asset gateway test等用于节点挂载与网关连通性检测。用户、授权与账号管理user / perm / account用户user list --search检索用户user create指定--username/--email/--password/--roleuser reset-password重置密码user unblock解除锁定user profile查看当前用户user my-assets查看当前用户可访问的资产user group members查询组成员。授权perm create把用户/用户组 资产/节点 动作绑定成资产授权AssetPermissionperm users/perm assets反向查询规则覆盖范围。账号凭据account list --secret-type、account createaccount secret view查看某账号口令/密钥、account secret history查看改密历史account template list列出账号模板。其中敏感信息处理有专门设计utils/init.py 中定义了SENSITIVE_KEYSpassword、secret、token、access_token、refresh_token、private_key、ssh_key 等输出时统一以********掩码避免密钥回显到终端或 Agent 上下文。会话与审计session / audit / opssession list --active只列出进行中的连接session replay获取会话回放信息session kill强制终止风险会话session command list --risk检索含风险命令的记录session terminal list / status查看 KoKo/Lion 等终端组件状态。audit login / operate / ftp / password / activity分别对应登录审计、操作审计、FTP 传输、改密审计与用户活动日志直接满足等保与合规审计场景。ops job-list / job-log / adhoc-list / playbook-list覆盖 JumpServer 的运维作业与自动化编排查看。输出格式给人看表格给机器看 JSONREADME 明确了两种输出Table默认人类可读与JSON--json-output供程序化消费。源码则将其扩展为三种格式见 output.py几乎所有数据类子命令都接受--output / -o参数cli-anything-jumpserver asset list --output json | jq .results[0] cli-anything-jumpserver user list --search admin --json-output cli-anything-jumpserver system settings --output yaml格式化规则为json输出带缩进、保留 UTF-8 的 JSONyaml输出多行 YAMLtable自动对齐列宽单列上限 50 字符、超出截断加...并在尾部打印结果计数。全局层面还提供了--json与--json-output两个等价 flag见 jumpserver_cli.py即便不逐条指定-o json也能让整条命令以 JSON 消费is_json_mode()会沿 Click context 链自动识别任一层的 JSON 偏好错误也会以{status:error,message:...}形式输出到 stderr方便 Agent 结构化解析。状态模型Session 与 CLIState 双文件持久化这是该 Harness 区别于纯无状态 curl 封装的核心设计JUMPSERVER.md 给出了完整的持久化字段图景Session → ~/.jumpserver-cli/session.json ├── base_url 堡垒机 URL ├── username 已认证用户名 ├── token Bearer API Token ├── token_expiry Token 过期时间戳 ├── refresh_token 刷新凭据 ├── org_id 当前组织多组织 ├── org_name 组织名 └── verify_ssl SSL 校验开关 CLIState → ~/.jumpserver-cli/state.json ├── current_org_id / current_org_name 当前组织 ├── selected_asset_ids / selected_node_ids 批量操作选中集 ├── last_filters 最近筛选条件 ├── pagination 分页状态limit/offset └── dry_run 只读演练开关Session由 session.py 实现save()/load()/clear()负责 JSON 落盘与删除is_authenticated()同时校验 token 存在性与过期时间。CLIState由 state.py 实现维护当前组织、批量操作选中资产/节点、最近筛选与分页支持reset_state()全局重置——这让 Agent 在选中一批资产→批量授权/改密→清除选中的多步工作流中可以保持上下文。JumpServerClient内置了重试策略session.py对 429/500/502/503/504 做最多 2 次重试、退避因子 0.5s且仅作用于幂等的 GET/HEAD/OPTIONS同时提供paginate()生成器自动翻页抓取全量结果。Dry Run 安全模式与错误处理Dry RunJUMPSERVER.md 规定所有变更类命令都支持--dry-run。以asset create --dry-run为例源码会打印计划动作与完整 payload 后直接返回不发起任何 API 调用commands_asset.py。这使 AI Agent 在执行破坏性变更前可以先宣读计划再由人类确认。cli-anything-jumpserver asset create \ --name web-prod-01 --address 10.0.0.10 --platform 1 --dry-run # 输出{action:create,endpoint:assets/hosts/,data:{...}}错误处理CLIError继承click.ClickException承载面向用户的错误信息JSON 模式下以结构化{status:error,message:...,detail:...}输出到 stderrutils/init.pyHTTP 层错误在require_auth/handle_api_error中被统一转换为 CLIError 并附带 API detail底层requests异常、KeyboardInterrupt、click.Abort等也在cli_main()中集中兜底处理并映射为合理的退出码见 jumpserver_cli.py。交互式 REPL 模式不带子命令直接启动即进入 REPL等价于--interactivecli-anything-jumpserver # 或 cli-anything-jumpserver -i启动横幅显示版本与当前连接状态已连接则提示Connected as user url提示符为jumpserver支持help按功能分组浏览命令、help command查看单条命令帮助内置Tab 补全补全列表来自预注册的可用命令集见 jumpserver_cli.py并支持exit/quit/CtrlD退出。需要说明的是从 JUMPSERVER.md 的 Known Limitations 看REPL 的补全目前是命令级而非上下文感知级例如不会根据--type枚举可选值。测试无需后端的单元测试与需要实例的 E2EREADME 提供了两套测试命令对应仓库内的两个测试文件# Unit tests (no backend required)——无需真实 JumpServer cd jumpserver/agent-harness pytest cli_anything/jumpserver/tests/test_core.py -v # E2E tests (requires JumpServer instance)——需要真实实例 JUMPSERVER_URLhttps://jumpserver.example.com \ JUMPSERVER_TOKENyour_token \ pytest cli_anything/jumpserver/tests/test_full_e2e.py -v依据 JUMPSERVER.md 的测试摘要共103 个测试59 个单元测试 44 个 E2E报告为 100% 通过单元测试覆盖Session、Client、State、Output 格式化、工具函数E2E 测试覆盖CLI 发现、Help 输出、参数校验、Dry Run、输出格式与完整工作流场景。E2E 依赖JUMPSERVER_URL与JUMPSERVER_TOKEN两个环境变量印证了 README 中Private Token是自动化接入含 CI/Agent的主要认证方式。已知边界与适用前提为保证使用预期README 配套 SOP JUMPSERVER.md 记录了四条已知限制值得在接入前评估依赖网络所有数据操作命令都实时请求 JumpServer API命令执行期间需保持实例可达无本地缓存资产/用户不落本地缓存每次查询都打 APIREPL 补全粒度Tab 补全为命令级尚未做到参数值级上下文感知无 WebSocket 能力不支持会话日志流式推送、终端状态流式上报等基于 WebSocket 的操作。此外需要注意 Python 版本以 setup.py 的3.11为最终门槛README 写作 Python 3.10部署端应准备 JumpServer v3.0 且 API 可访问的实例。小结cli-anything-jumpserver的本质是一层面向人机双端的 JumpServer 控制面对外以统一 CLI table/json/yaml 输出抹平了资产、用户、授权、账号、会话、审计与运维七大域的操作差异对内以~/.jumpserver-cli/下的 session/state 双文件实现认证与多步工作流状态保持以--dry-run、敏感字段掩码与结构化错误处理约束 AI Agent 的破坏性操作。对照源码jumpserver_cli.py、core/session.py、core/state.py、utils/init.py即可逐一验证文中行为深入演练可参考配套 SOP JUMPSERVER.md 与技能定义 skills/SKILL.md。【免费下载链接】CLI-AnythingCLI-Anything: Making ALL Software Agent-Native -- CLI-Hub: https://clianything.cc/项目地址: https://gitcode.com/GitHub_Trending/cl/CLI-Anything创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考