rustsdcmcp

rustsdcmcp

Async Rust Model Context Protocol server for HPE Juniper Security Director Cloud

a mechub project — sovereign network-security automation

Unofficial / community project. This is an independent community project

and does not claim affiliation with or endorsement by Hewlett Packard

Enterprise or Juniper Networks. Product names and trademarks are used only to

identify the systems with which the software interoperates.

---

rustsdcmcp exposes HPE Juniper Security Director Cloud (SDC) to MCP clients as a bounded, auditable tool surface. SDC is the HPE Juniper SASE portal for an SRX estate, so this server talks to that management plane rather than to any single firewall. Where rustjunosmcp talks NETCONF to individual SRX devices, rustsdcmcp talks HTTPS REST to the portal that governs them.

That distinction has a large blast radius: one SDC action can affect many managed SRX devices. Strict approval, credential-safe attribution, and bounded I/O therefore protect the management plane rather than merely decorate it.

Current status

rustsdcmcp exposes 80 MCP tools (v0.6.0 and main; v0.3.1 shipped 78; v0.2.0 shipped 74): 60 bounded read tools and 20 change-control tools. The surface covers the part of the SDC API that manages SRX devices and their policy; the rest of the product's API is deliberately out of scope.

Every mutation is reachable only through prepare → independent approval → apply. A wildcard token scope deliberately grants no write tool, so each must be named explicitly when a token is minted.

Live validation against SDC has gone well beyond read-only. On 2026-08-07 a full prepare → approve → apply policy deploy ran against the lab tenant and reached a managed vSRX, which is how the co-management behaviour in #23 was discovered: within hierarchies SDC owns, objects not reachable from a policy SDC imported are deleted on deploy. Interfaces, routing, system, and the management instance were untouched. The full boundary and the observed diff are in docs/operations.md. JobStatus and DeviceStatusEntry are validated against live preview and deploy responses.

On 2026-08-12 the certificate and licence readers, BulkSyncDevices, and the template endpoints were exercised live. Device sync imports into SDC rather than pushing to the device, but reconciles inventory only and does not clear device_config_state: OUT_OF_BAND_CHANGED.

Read-path security properties were last verified live on 2026-08-07 against commit ea81805d2b4b97df9bdd3f70423e047524896a3d with mecmcp v0.5.0. The transport and scope preflight were replaced afterwards in e28d0cc and 369f9bb, so that result no longer speaks for current main; no lab SDC tenant was available to repeat it live. On 2026-10-06, against commit 2036523 with mecmcp v0.26.0, the automated integration suite was re-run instead — cargo test --workspace, 258 passed, 0 failed — which covers: requests with a missing bearer are refused (crates/rustsdcmcp/tests/http_boundary.rs::router_requires_bearer), out-of-scope tenants are refused (crates/rustsdcmcp/tests/http_boundary.rs::out_of_scope_tenant_is_refused), exact tool and tenant scope enforcement with read/write tool disjointness (crates/rustsdcmcp/src/server.rs scope unit tests, crates/rustsdcmcp/tests/tool_contract.rs), and secret-key redaction of responses (crates/rustsdcmcp-core/src/redact.rs unit tests). The remaining properties from the 2026-08-07 live audit have not been re-verified on current main; this run is not a substitute for the live-tenant exercise and does not re-establish one.

Observed response shapes and the remaining endpoint questions are tracked in docs/sdc-api/README.md.

Download

The current release, v0.6.0, attaches a checksummed, cosign-signed LXC install tarball (rustsdcmcp_0.6.0_amd64.tar.gz) as a release asset. Download and verify it, or build from approved source below.

A linux/amd64 container image is published for that tag to ghcr.io/mechubsec/rustsdcmcp:0.6.0 and is publicly pullable with no authentication.

Build from approved source

rust-toolchain.toml pins the build toolchain at 1.99.0; the declared MSRV in Cargo.toml is 1.89. Operators must bind their checkout to the commit they intend to ship before building, testing, or packaging — the release tag is the usual choice:

approved_commit=$(git rev-parse v0.6.0^{commit})

git checkout --detach "$approved_commit" test "$(git rev-parse HEAD)" = "$approved_commit" cargo build --release --locked cargo test --workspace --locked scripts/build-package.sh cp examples/sdc.example.json /secure/operator/path/sdc.json

In that configuration, credential_env names the external process variable; the credential itself never belongs in JSON. For a local commit-addressed package, verify the newly built archive and its embedded BUILD-INFO from the approved commit directory—never glob across dist/ because the checksum records only the archive basename:

artifact_dir="dist/$approved_commit"

mapfile -t archives < <(find "$artifact_dir" -maxdepth 1 -type f -name 'rustsdcmcp_*_amd64.tar.gz' -print) test "${#archives[@]}" -eq 1 archive="${archives[0]}" (cd "$artifact_dir" && sha256sum -c "$(basename "$archive").sha256") package_root=$(tar -tzf "$archive" | sed -n '1s#/.*##p') test -n "$package_root" tar -xOf "$archive" "$package_root/BUILD-INFO" | grep -Fx "git_commit=$approved_commit"

Local stdio client

--transport stdio (the default) runs the server as a child process of the MCP client, with no listening socket and no bearer token. examples/mcp.json.example is a .mcp.json entry for that. Copy examples/sdc.example.json to the --device-mapping path, fill in the tenant, and chmod 0600 it: the server refuses a config file more permissive than 0640. --state-file overrides the config's /var/lib/rustsdcmcp/changeset-state.json, which a desktop user cannot normally write.

The credential reaches the server through the variable that credential_env names (SDC_API_TOKEN in the example). ${SDC_API_TOKEN} is expanded from the client's environment, so the token stays out of the JSON file. A client that does not expand ${...} needs the variable exported in the environment it is launched from.

A stdio caller is unauthenticated, so every write tool (prepare, approve, apply) refuses it: stdio is a read-only surface. Change-controlled writes need the streamable-HTTP transport with a scoped bearer token.

Tool listing mode

--tool-mode full|compact (env MCP_TOOL_MODE, default full) controls what tools/list advertises. compact lists only list_sdc_resources, get_sdc_resource, get_sdc_tenant_scope and the change-set tools (get_sdc_change_set, get_sdc_change_set_details, approve_sdc_change_set, apply_sdc_change_set) to keep the client's tool context small. It is listing only: it composes with token scopes and never widens them, every tool stays callable, and the token's tool and tenant scopes still authorize each call.

Docker quick start

For running the published container image, see HOW-TO-SETUP-DOCKER.md.

Debian 13 LXC quick start

For building an LXC from scratch, see HOW-TO-SETUP-LXC.md.

Prerequisites:

• Debian 13 AMD64; an unprivileged LXC is recommended.
• 1 vCPU, 512 MiB RAM, 512 MiB swap, and 4 GiB disk for the minimum profile.
• Working DNS and time synchronization, plus outbound HTTPS to api.sdcloud.juniperclouds.net.
• Root or equivalent operator access inside the LXC.

Download the signed v0.6.0 release tarball (or build one from approved source — see Build from approved source above) and install the verified package:

set -euo pipefail

mapfile -t archives < <(find . -maxdepth 1 -type f -name 'rustsdcmcp_0.6.0_amd64.tar.gz' -print) test "${#archives[@]}" -eq 1 archive="${archives[0]}" sha256sum -c "$archive.sha256" package_root=$(tar -tzf "$archive" | sed -n '1s#/.*##p') test -n "$package_root" tar -xzf "$archive" sudo "$package_root/packaging/lxc/install.sh"

Create the configuration and credential file without exposing a credential:

sudo install -o root -g rustsdcmcp -m 0640 \

/etc/rustsdcmcp/sdc.json.example /etc/rustsdcmcp/sdc.json sudoedit /etc/rustsdcmcp/sdc.json sudo install -o root -g root -m 0600 /dev/null \ /etc/rustsdcmcp/credentials.env sudoedit /etc/rustsdcmcp/credentials.env

sdc.json must retain the HTTPS SDC endpoint, use the desired local tenant alias, and set expected_tenant_id to the operator-obtained SDC tenant ID. The credentials file contains one shell-compatible assignment using the name from credential_env, for example SDC_API_TOKEN=...; never put a real value in the README or JSON.

Create the initial exact 14-tool read-only grant. The redirect destination must already be mode 0600; the output is a one-time bearer token.

sudo /usr/local/bin/rustsdcmcp token add \

--tokens-file /etc/rustsdcmcp/tokens.json \ --device-mapping /etc/rustsdcmcp/sdc.json \ --name sdc-read \ --devices production \ --tools get_sdc_tenant_scope,list_sdc_devices,get_sdc_device,list_sdc_firewall_policies,get_sdc_firewall_policy,list_sdc_nat_policies,get_sdc_nat_policy,list_sdc_resources,get_sdc_resource,get_sdc_preview_status,get_sdc_deploy_status,get_sdc_preview_device_result,get_sdc_deploy_device_result,get_sdc_change_set \ --actor-type human > /secure/local/path/rustsdcmcp-sdc-read-token

Start the service and access it through an authenticated SSH tunnel:

sudo systemctl enable --now rustsdcmcp.service

sudo systemctl --no-pager --full status rustsdcmcp.service sudo ss -ltnp 'sport = :30032' ssh -N -L 30032:127.0.0.1:30032 root@your-deployment-host

The expected listener is only 127.0.0.1:30032. While the tunnel is active, the local MCP client uses http://127.0.0.1:30032/mcp. Each installation supplies its own SSH host; the server is never exposed directly.

Security commitments

• External credentials use restrictive file modes and never belong in JSON.
• Startup verifies the configured identity against expected_tenant_id.
• Bearer tokens carry exact tool and tenant scopes.
• Request, response, and page sizes are bounded.
• Audit attribution is credential-safe and target values receive HMAC redaction.
• Mutations require two-principal prepare → approve → apply change control.
• There is no direct deploy tool and no unauthenticated write path.
• A wildcard token scope grants no write tool. --tools '*' yields the read surface only; every write tool must be named explicitly when minting a token.

Detailed deployment, recovery, audit-retention, and write-workflow guidance is in docs/operations.md.

--lab-mode

--lab-mode waives the second principal, for a single-operator lab where two-person control is theatre rather than a control. It is off by default and should stay off anywhere the estate matters.

What it does and does not change:

• The waiver is applied automatically when the change set is created. There is no waive tool, and the flow stays prepare → apply, identical to production.
• Planning, the plan digest, drift detection, and apply-time revalidation all still run. Lab mode removes the *second reviewer*, not the change record.
• No approver is ever fabricated. A waived change set records `ap