dsh-jumpserver

A local DeepSeek Harness plugin that manages JumpServer v3.7.1 safely through curated, plan-and-approve tools.

English · 中文

---

What it does

For DeepSeek Harness (dsh): lets an Operator manage JumpServer v3.7.1 safely with its own JumpServer API Key. Instead of exposing the huge Swagger surface, it registers a small set of intention-level Curated Management Tools, and requires every state-changing Management Operation to be previewed as an Execution Plan, explicitly confirmed, and executed only while the plan is still Fresh. No Connection Secret ever reaches the model context.

Built-in safety:

• Curated tool surface — only intention-level tools are registered (e.g. plan_label_asset, apply_plan), never raw endpoints; unavailable capabilities are hidden with a reason via startup Capability Negotiation rather than failing unexpectedly
• Plan + approve — every plan_* returns a single-use, agent/session-bound, process-local Plan ID (expires in 5 minutes); apply_plan obtains Harness-native allowed-once approval, re-reads critical state to verify Freshness, enforces the Impact Limit, and only then executes; rejected, cancelled, unavailable, expired, stale, or missing plans fail closed — no state-changing request is ever sent
• No secret disclosure — passwords, private keys, tokens, and session cookies are categorically excluded from any tool output, plan, error, or log; secret operations (generate / push / rotate) discard the actual value and return metadata only
• Scope + continuity — organization-scoped connections cannot reach Control Plane / organization tools; a Global Managed Connection is required, and Control Plane writes are expressed as Field-Change diffs, never whole-object replacement; identity/RBAC changes that would remove the last usable administrator (or self-lock) are rejected even when confirmed
• Bounded results — queries return Result Pages of at most 50 objects with a continuation cursor; the query match limit is 500
• Safety semantics — already-satisfied state returns a No-op Result; uncertain writes return Ambiguous Outcome (with state-inspection guidance) instead of automatic retry; bulk failures return a Partial Result, halting on the first failure with no automatic rollback

Behavior	Description
Secret-safe	Connection Secrets never enter tool output, plans, errors, or logs
Fail closed	Any non-allowed-once approval, expired/stale/consumed/mis-bound plan, or unknown connection blocks the write
No raw escape hatch	No Swagger-derived or generic raw tools; no adhoc shell / arbitrary script execution
No auto retry / rollback	Uncertain writes return Ambiguous Outcome; partial failures stop and require a new explicit operation
TLS always verified	Private CA is an explicit Trusted CA choice; insecure bypass is unsupported

Why

The official JumpServer MCP auto-exposes the entire Swagger API as tools: an uncontrollable surface, unconstrained inputs, no approval step, and a real risk of leaking sensitive data and secrets into model context. dsh-jumpserver replaces raw endpoints with clear intents, authenticates with the Operator's own API Key, and constrains every change with plan-and-approve so JumpServer remains the outer authorization boundary.

Quick start

Install and load the plugin inside DeepSeek Harness with dsh plugin add (GitHub direct install — npm publication is deferred):

dsh plugin --profile web add github:easyv-ai/dsh-jumpserver

The plugin declares a dsh.bundle manifest and registers every curated tool as a first-party Harness tool. Configure the Managed Connection in the Harness Settings panel — open Settings → jumpserver and fill in:

Field	Meaning
name	Managed Connection name (e.g. prod-cn)
url	JumpServer base URL
organizationId	Organization id for org-scoped operations
environment	production / non-production / unknown
accessKeyId	JumpServer AccessKey ID
accessKeySecret	AccessKey Secret — stored redacted and displayed masked by Harness (role: secret), never persisted in cordis.yml and never in tool output
isGlobal	Enable for a Global Managed Connection (Control Plane)
trustedCaPem	Optional private CA PEM

Editing the card hot-reloads the connection and re-registers all tools; no restart is needed. Until configured, the plugin logs a hint and registers no tools.

To develop or embed the plugin directly (without dsh), clone and build:

git clone git@github.com:easyv-ai/dsh-jumpserver.git
cd dsh-jumpserver
pnpm install
pnpm typecheck   # tsc --noEmit
pnpm test        # vitest run (66 contract tests)
pnpm build       # emits lib/

Integrating into the Harness

Enter a ManagedConnection at startup through the local CLI (so the AccessKey Secret is never echoed or persisted):

import { ConnectionRegistry, establishTrustedConnection, createDshJumpserver, defaultMakeGateway } from './src/index.js'

const registry = new ConnectionRegistry()
await establishTrustedConnection(
  {
    name: 'prod-cn',
    url: 'https://jumpserver.example.com',
    organizationId: 'org-1',
    environment: 'production',          // 'production' | 'non-production' | 'unknown'
    accessKeyId: 'your-ak-id',
    accessKeySecret: 'your-ak-secret',  // interactively supplied, never persisted
    // trustedCaPem: '-----BEGIN CERTIFICATE-----...'   // optional private CA
  },
  { registry, createGateway: (s) => defaultMakeGateway(s, registry.getSecret(s.name)!) },
)

const { runner } = createDshJumpserver({
  registry,
  approval,                                  // Harness-native ApprovalService (allowed-once)
  makeGateway: (summary, secret) => defaultMakeGateway(summary, secret),
})

A change end to end

// 1. Preview — returns a single-use planId
const preview = await runner.run('prod-cn', 'plan_label_asset',
  { id: 'a-1', add: ['prod'], label: 'db-1' }, 'agent-1', 'session-1')

// 2. Apply — requires explicit allowed-once approval; stale/rejected fails closed
const result = await runner.run('prod-cn', 'apply_plan',
  { planId: preview.planId }, 'agent-1', 'session-1')

Tool catalog

Query / read (riskTier: query):

Domain	Tools
Assets & topology	search_assets search_nodes search_domains search_platforms search_labels
Accounts	search_accounts
Authorization & access	inspect_access search_acl search_command_filters
Sessions & audit	search_sessions search_commands search_file_transfers
Templates	search_templates
Identity & RBAC	search_users search_user_groups search_roles search_org_membership
Organizations	search_organizations

Plan / write (each requires apply_plan approval):

Domain	Tools
Assets & topology	plan_create/update/delete_asset|node|domain plan_bulk_delete_assets plan_label_asset
Account lifecycle	plan_bind_account plan_update_account plan_generate_secret plan_push_secret plan_rotate_secret
Authorization & access	plan_grant_access plan_revoke_access plan_change_acl plan_change_command_filter
Sessions	plan_terminate_session
Templates	plan_run_template plan_cancel_template
Identity & RBAC	plan_create/update/delete_user plan_create/update/delete_group plan_add/remove_group_members plan_assign/revoke_role plan_create/remove_org_membership
Organization & Control Plane	plan_create/update/delete_organization plan_change_setting

Execution Handle (riskTier: query): template_execution_status template_execution_output

Generic apply: apply_plan

Architecture

curated tools (intent vocabulary)
   └── ToolRunner ............ Global Managed Connection gate, dispatch
        ├── plan_* ............ builds an immutable ExecutionPlan
        └── apply_plan ........ executor: claim → freshness → impact → approval → execute
             └── OperationExecutor
                  └── JumpServerGateway (replaceable seam)
                       └── HttpJumpServerGateway (signed requests, TLS, org header)

Module	Responsibility
plan-store.ts	Execution Plans — in-memory, 5-min TTL, single-use, agent/session-bound
approval.ts	Harness-native allowed-once approval; everything else fails closed
executor.ts	apply_plan orchestration (freshness, Impact Limits, Ambiguous Outcome)
risk.ts	Risk Tiers and Impact Limits (query 500 / standard 50 / highest 25)
outcomes.ts	success / noop / ambiguous / partial / failure
curated.ts	Tool registry + Global Managed Connection gating
http-jumpserver-gateway.ts	Signed AccessKey HTTP requests, TLS, org header
endpoints.ts	Centralized v3.7.1 endpoint map (single place to correct paths)

Security model

• No secret disclosure: Connection Secrets never enter tool output, plans, errors, or logs
• No raw API escape hatch: no Swagger-derived or generic raw tools; no adhoc shell / arbitrary script execution
• Fail closed: any non-allowed-once approval, expired/stale/consumed/mis-bound plan, or unknown connection blocks the write
• Scope + continuity: organization-scoped connections can't reach global tools; last-admin / self-lock removals are rejected
• No automatic retry or rollback: uncertain writes return Ambiguous Outcome; partial failures stop and require a new explicit operation
• TLS always verified: private CA is an explicit Trusted CA choice; insecure bypass is unsupported

Development

pnpm typecheck     # strict tsc --noEmit
pnpm test          # 66 contract tests across all phases
pnpm test:watch

Tests exercise the external contract at the tool seam against a scriptable FakeGateway, covering approval outcomes, plan expiry/single-use/binding, stale-plan rejection, Impact Limits, secret non-disclosure, Administrator Continuity, paging, and no-op / ambiguous / partial semantics.

License