dsh-jumpserver
A DeepSeek Harness plugin for querying and managing JumpServer assets through conversation, authenticated with a JumpServer AccessKeyID/AccessKeySecret pair (HTTP Signature).
> Project status: v0.8.0. Read-only asset, user, account, permission, session, command-audit, user-group, and command-filter lookups are implemented, plus create/update/delete for assets, accounts, users, asset-permission rules, user groups, command groups, and command filters, and password/MFA/SSH-key resets for users — all behind a mandatory native user-approval prompt. Session termination and ticket approval remain intentionally out of scope given JumpServer's role as a bastion/PAM system.
Why dsh-jumpserver
- List and inspect JumpServer assets, users, accounts, asset-permission rules, terminal sessions, executed commands, user groups, and command-filter rules by keyword or filter.
- Create, update, and delete assets, accounts, users, asset-permission rules, user groups, command groups, and command filters, and password/MFA/SSH-key resets for users — every write requires an explicit native user-approval prompt before it runs; the model cannot bypass it.
- Refuses to delete or reset the password of superuser (administrator) accounts, and refuses to create asset-permission rules or command filters with broad or "grant access to everything"/"all users"/"all assets" matching — both are enforced by the tools themselves, not just documented as a convention.
- Never exposes secrets on read: account secrets/passphrases and user passwords/public keys/MFA secrets are stripped before a response reaches the model, even if the JumpServer API includes them.
- Authenticate with a JumpServer AccessKeyID/AccessKeySecret pair using JumpServer's native HTTP Signature scheme (
hmac-sha256), the same mechanism documented in JumpServer's own developer docs. - Keep the AccessKeySecret in the local DSH credential store; it is never echoed back to the browser.
Requirements
| Component | Supported baseline |
|---|---|
| Node.js | 20.11 or newer |
| DeepSeek Harness | 0.1.0-rc.6 |
| JumpServer | REST API v1 (Access Key authentication) |
Installation
For local development, install from the local path:
npm ci
dsh plugin --profile add link:/absolute/path/to/dsh-jumpserverOnce published, install a released, immutable tag whenever possible:
dsh plugin --profile add github:easyv-ai/dsh-jumpserver#v<version>Install the mutable development branch only for testing:
dsh plugin --profile add github:easyv-ai/dsh-jumpserverRestart the selected DSH profile after installation. On Windows, use an absolute link:C:/path/to/dsh-jumpserver path.
Configuration
In DSH Web, open Settings → Plugins → JumpServer asset lookup.
Configure:
- JumpServer URL: the absolute base URL, for example
https://jumpserver.example.com. - Access Key: create one from the JumpServer web console under your personal API Key list.
- Secret Key: paired with the Access Key above.
The Access Key/Secret Key use DSH's privileged loopback credential RPC — write-only, the stored values are never read back or displayed. The URL is stored in the jumpserver settings namespace as a non-secret field, so it is read back in plaintext and shown in the card for verification.
HTTP and HTTPS both work out of the box — internal deployments without TLS certificates can use an http:// URL with no extra setup. Note that plain HTTP sends the signed request (though not the secret itself) over an unencrypted channel; prefer HTTPS over untrusted networks. To enforce HTTPS only, disable it in plugin configuration:
allowInsecureHttp: falseThe credential reference names default to JUMPSERVER_ACCESS_KEY_ID / JUMPSERVER_ACCESS_KEY_SECRET and can be changed with akRef / skRef in the plugin configuration.
JumpServer permissions
Create the AccessKey under a JumpServer account that only has read access to the assets you want visible to the assistant. Avoid using a super-admin account's key for this integration.
Tools
Read-only tools paginate with limit (1-100, default 20) / offset (default 0) where applicable.
| Tool | Behavior |
|---|---|
jumpserver_list_assets | Lists assets with an optional search keyword. |
jumpserver_get_asset | Gets full detail for one asset by id, including protocols and domain. |
jumpserver_list_users | Lists users with an optional search keyword. Never returns passwords, public keys, or MFA secrets. |
jumpserver_get_user | Gets full detail for one user by id. Never returns passwords, public keys, or MFA secrets. |
jumpserver_list_accounts | Lists accounts (asset login credentials), optionally filtered by asset id or username. Never returns secrets or passphrases. |
jumpserver_get_account | Gets full detail for one account by id. Never returns the secret or passphrase. |
jumpserver_list_permissions | Lists asset-permission rules, optionally filtered by userId or assetId. |
jumpserver_list_sessions | Lists terminal (audit) sessions, optionally filtered by user, asset, or isFinished. |
jumpserver_create_asset | Write. Creates an asset (name, address, platform required; comment, isActive optional). Requires native user approval. |
jumpserver_update_asset | Write. Updates an existing asset by id; only the fields you pass are changed. Requires native user approval. |
jumpserver_delete_asset | Write, irreversible. Permanently deletes an asset by id. Requires native user approval. |
jumpserver_create_account | Write. Creates an account (username, asset required; name, secretType, secret, passphrase, privileged, isActive, comment optional). Requires native user approval. See "Handling account secrets" below. |
jumpserver_update_account | Write. Updates an existing account by id; only the fields you pass are changed. Can rotate secret/passphrase. Requires native user approval. |
jumpserver_delete_account | Write, irreversible. Permanently deletes an account by id. Requires native user approval. |
jumpserver_create_user | Write. Creates a platform user (name, username, email required; comment, isActive optional). Never sets an initial password — use jumpserver_update_user for that. Requires native user approval. |
jumpserver_delete_user | Write, irreversible. Permanently deletes a user by id. Refuses to delete superuser (administrator) accounts. Requires native user approval. |
jumpserver_update_user | Write. Updates an existing user by id; only the fields you pass are changed (name, email, comment, isActive). Can also reset the login password to a specific value (password). Refuses to change the password of superuser (administrator) accounts — other fields may still be updated. Requires native user approval. See "Handling account secrets" below — the same exposure tradeoff applies to the password value. |
jumpserver_reset_user_mfa | Write. Unbinds a user's MFA/OTP device by id, forcing them to set it up again on next login. Refuses to act on superuser accounts. Requires native user approval. |
jumpserver_reset_user_ssh_key | Write. Clears a user's SSH public key used to log in to JumpServer itself (not an asset account key) by id. Refuses to act on superuser accounts. Requires native user approval. |
jumpserver_create_permission | Write. Creates an asset-permission rule (name required; assets, accounts required as non-empty UUID arrays; at least one of users/userGroups required, also non-empty). Rejects broad or "grant access to everything" matching — there is no all/node-wide option. Requires native user approval. |
jumpserver_update_permission | Write. Updates an existing rule by id; only the fields you pass are changed. Any array field you do pass (users, userGroups, assets, accounts) must be non-empty. Requires native user approval. |
jumpserver_delete_permission | Write, irreversible. Permanently deletes an asset-permission rule by id, revoking the access it granted. Requires native user approval. |
jumpserver_list_commands | Lists executed session commands (command audit log), optionally filtered by asset, account, user, sessionId, or riskLevel. Command output is truncated to 500 characters per row. |
jumpserver_list_user_groups | Lists user groups with an optional search keyword. A group by itself grants no asset access. |
jumpserver_get_user_group | Gets full detail for one user group by id, including its member user ids. |
jumpserver_create_user_group | Write. Creates a user group (name required; users, comment optional). Requires native user approval. |
jumpserver_update_user_group | Write. Updates an existing group by id; only the fields you pass are changed. If you pass users, it must be non-empty. Requires native user approval. |
jumpserver_delete_user_group | Write, irreversible. Permanently deletes a user group by id; member users themselves are not deleted, but any permission rules referencing the group lose that grant. Requires native user approval. |
jumpserver_list_command_groups | Lists command groups (named sets of command patterns), optionally filtered by a search keyword. A command group has no effect until bound to a command filter. |
jumpserver_get_command_group | Gets full detail for one command group by id, including its full pattern content. |
jumpserver_create_command_group | Write. Creates a command group (name, content required; type, ignoreCase, comment optional). Requires native user approval. |
jumpserver_update_command_group | Write. Updates an existing command group by id; only the fields you pass are changed. Requires native user approval. |
jumpserver_delete_command_group | Write, irreversible. Permanently deletes a command group by id; any command filter bound to it loses that matching rule. Requires native user approval. |
jumpserver_list_command_filters | Lists command filters (security rules that reject/warn on/accept matching commands), optionally filtered by a search keyword. |
jumpserver_get_command_filter | Gets full detail for one command filter by id, including its user/asset/account scope and bound command groups. |
jumpserver_create_command_filter | Write. Creates a command filter (name, users, assets, accounts, commandGroupIds required as non-empty UUID arrays; action — reject/warning/accept, default reject — priority, comment, isActive optional). Rejects "all users"/"all assets"/"all accounts" scope — there is no broad-match option. Setting action to accept is flagged in the approval prompt as a security downgrade. Requires native user approval. |
jumpserver_update_command_filter | Write. Updates an existing filter by id; only the fields you pass are changed. Any scope array you do pass (users, assets, accounts, commandGroupIds) must be non-empty. Changing action to accept is flagged in the approval prompt as a security downgrade. Requires native user approval. |
jumpserver_delete_command_filter | Write, irreversible. Permanently deletes a command filter by id. The approval prompt shows the rule's current action (fetched just before asking) so you can see whether you're removing an active reject/warning protection before approving. Requires native user approval. |
Session termination and ticket approval are not implemented, and are not currently planned — see "Out of scope" below.
Out of scope
jumpserver_terminate_session was evaluated but dropped: JumpServer's /api/v1/terminal/tasks/kill-session/ endpoint has no documented request-body schema in the standard swagger export, so the exact contract could only be inferred, not confirmed. Ticket approval (/api/v1/tickets/...) is intentionally not implemented — it would let the assistant substitute for a human approval step that JumpServer's own workflow requires.
Write-tool approval
Every call to an asset or account write tool is intercepted by a tools/pre-execute gate (the same pattern dsh-grafana uses for grafana_push) and always downgraded to an explicit native approval prompt — the model cannot execute a write without it. The prompt shows the operation and the fields being changed; for updates, only the fields you pass are sent, and for deletes the current name/address (assets) or username/asset (accounts) are read back once the delete succeeds. The update and delete tools both re-check that the target exists (an extra GET) before attempting the write, and fail loudly instead of silently doing nothing if it's missing.
Handling account secrets
jumpserver_create_account and jumpserver_update_account accept an optional secret/passphrase value — the actual login credential for the target asset. This is a deliberate exception to this plugin's usual rule that secrets never enter the model's context: unlike the AccessKeySecret (which lives only in the DSH credential store and is never sent to the model), an account secret set through these tools passes through the tool-call arguments to reach JumpServer, and is therefore exposed to the conversation and whatever model provider processes it.
The approval prompt never displays the literal secret value — it only states whether a secret/passphrase is being set or changed — and the tool's return value never echoes it back either. But the redaction stops at the plugin boundary: if you ask the assistant to set a specific password, that password will appear in the conversation transcript up to that point. Prefer letting JumpServer generate/rotate credentials through its own automation (account push, change-secret executions) when the value itself must stay out of the model's context; use these tools' secret parameter only when you've explicitly accepted that tradeoff.
The same tradeoff applies to jumpserver_update_user's password parameter.
Security and data boundaries
- The AccessKeySecret never enters tool arguments, model messages, logs, or Git.
- Account secrets/passphrases and user passwords/public keys/MFA secrets are explicitly excluded from every read tool's output, field by field — not just omitted from a generic serializer. (Account write tools are the one exception; see "Handling account secrets" above.)
- Authenticated requests reject HTTP redirects to avoid forwarding signed requests to another origin.
- Non-loopback HTTP is disabled by default (see
allowInsecureHttp). - Requests have cooperative cancellation, timeouts, and bounded response sizes.
- Error responses expose only a bounded status/detail description.
idparameters are validated as JumpServer UUIDs before being placed in a request path, preventing path injection.- All returned fields (names, addresses, comments, usernames, etc.) are treated as untrusted data, not model instructions.
Development
npm ci
npm run verifyTests use Node's built-in test runner and mocked JumpServer responses.
License
MIT