rustjunosmcp

<p align="center"> <picture> <source media="(prefers-color-scheme: dark)" srcset="docs/assets/mechub-mark.svg"> <img src="docs/assets/mechub-mark-light.svg" width="72" alt="mechub mark"> </picture> </p> <h1 align="center">rust-junosmcp</h1> <p align="center"><strong>One MCP server for Juniper Junos and SRX devices, in Rust</strong><br> <em>a mechub project — sovereign network-security automation</em></p>

Unofficial / community project. This repository is an independent, community-driven project. It is not affiliated with, endorsed by, sponsored by, or supported by Hewlett Packard Enterprise or Juniper Networks. "HPE", "Juniper", "SRX", "JUNOS", "Security Director" and "Juniper Mist" are trademarks of their respective owners and are used here only to describe what this software interoperates with. Please direct support and licensing questions about those products to the respective vendors.

A Model Context Protocol server for Juniper Junos and SRX devices, written in Rust. One rust-junosmcp process gives an MCP client the core Junos tools and the SRX security workflows (45 tools by default), with per-token device and tool scopes, audit logging, and change control for configuration writes. It reads the same devices.json inventory as Juniper/junos-mcp-server.

The server runs on Linux only, in an LXC container or in Docker. The current version is 2.7.0. It is stable: see Stability for what that covers.

1. Install

Pick one path. Both end with the server on 127.0.0.1:30030/mcp behind bearer-token authentication. You need the same things either way:

• A devices.json inventory. Start from devices-template.json. Each device needs an auth object with a type (ssh_key or password).
• An SSH private key whose public half is installed for a NETCONF user on each device. Prefer keys to passwords.
• A known_hosts entry for each device. Host-key checking is strict. scripts/scan-known-hosts.sh builds the file from the inventory; check the fingerprints against a trusted source.
• Mode 0600 on devices.json, the key and tokens.json; the server refuses to start otherwise.

Docker

Prebuilt images are public and need no login:

• ghcr.io/mechubsec/rustjunosmcp
• docker.io/mechub/rustjunosmcp

The image runs as UID/GID 65532:65532 and has no shell. Its entrypoint already passes the inventory, state, known-hosts, lease, token-file and audit-key paths, so add only transport and bind flags. Do not repeat the entrypoint flags.

Verify the image signature first. Your inventory and SSH key get mounted into this image, so stop if the check fails. Pin the image by digest, so the bytes you verify are the bytes you run. A later release needs its own version and digest.

image=ghcr.io/mechubsec/rustjunosmcp:2.7.0@sha256:4eb477e50f05ed0a417f0dffb0f4049cf7ea2e8704ce89ecc10a8210aebc8bc4

cosign verify \
  --certificate-identity-regexp '^https://github\.com/mechubsec/mecmcp/\.github/workflows/reusable-release-image\.yml@' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  --certificate-github-workflow-repository mechubsec/rustjunosmcp \
  --certificate-github-workflow-trigger push \
  --certificate-github-workflow-ref refs/tags/v2.7.0 \
  "$image"

Then prepare the host paths:

mkdir -p junos-docker/keys junos-docker/state/device-leases junos-docker/state/staging
cd junos-docker
# Put devices.json and keys/id_ed25519 here, then pin each device's host key:
/path/to/rustjunosmcp/scripts/scan-known-hosts.sh \
    --inventory ./devices.json --known-hosts ./state/known_hosts
chmod 0600 devices.json keys/id_ed25519
sudo chown -R 65532:65532 devices.json keys state
sudo chmod 0700 keys state state/device-leases

Mint a token (below), then start it:

docker run -d --name junos-twoperson \
  -p 127.0.0.1:30030:30030 \
  -v "$PWD/devices.json:/etc/jmcp/devices.json:ro" \
  -v "$PWD/keys:/etc/jmcp/keys:ro" \
  -v "$PWD/state:/var/lib/jmcp" \
  "$image" \
  --transport streamable-http --host 0.0.0.0 --port 30030 \
  --allow-insecure-bind \
  --allowed-host 127.0.0.1:30030 --allowed-host localhost:30030 \
  --allowed-origin http://127.0.0.1:30030 --allowed-origin http://localhost:30030

Notes:

• private_key_path in devices.json is the in-container path, for example /etc/jmcp/keys/id_ed25519.
• Keep tokens.json in the mounted state directory. Do not bind-mount it as a single file. Token commands replace the file, so a single-file mount keeps the old copy and a revoked token stays valid after a reload.
• --allowed-host and --allowed-origin carry the port the client dials, which is the published port, not the container's 30030.
• Without --lab-mode this is two-person mode. To run lab mode, add --lab-mode as the last argument. See section 2.
• --audit-journald does not work in a container (no journald socket). Read the audit stream with docker logs.

Full walk-through, image digest pinning and troubleshooting: docs/HOW-TO-SETUP-DOCKER.md.

LXC (Proxmox)

The container must be Debian 13 (trixie). The published binary needs GLIBC_2.39 and Debian 12 ships 2.36, so the service would fail at start with a "GLIBC_2.39 not found" error after an otherwise clean install. Create it unprivileged with --features nesting=1 (systemd 257 needs it). 512 MB and one core is enough.

Use the release tarball. Do not build the binary on your workstation and copy it in: a newer glibc than the container's will not load.

The checksum proves the download is intact. The signature proves it came from this project's release workflow. Stop if either check fails.

version=2.7.0
base="https://github.com/mechubsec/rustjunosmcp/releases/download/v${version}"
tarball="rust-junosmcp_${version}_amd64.tar.gz"
curl -fLO "$base/$tarball"
curl -fLO "$base/$tarball.sha256"
curl -fLO "$base/$tarball.cosign.bundle"

sha256sum -c "$tarball.sha256"
cosign verify-blob \
  --certificate-identity-regexp '^https://github\.com/mechubsec/mecmcp/\.github/workflows/reusable-sign-release-tarball\.yml@' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  --certificate-github-workflow-repository mechubsec/rustjunosmcp \
  --certificate-github-workflow-trigger release \
  --certificate-github-workflow-ref "refs/tags/v${version}" \
  --bundle "$tarball.cosign.bundle" "$tarball"

pct push <vmid> "$tarball" /tmp/pkg.tar.gz
pct exec <vmid> -- bash -lc "cd /tmp && tar xzf pkg.tar.gz && cd rust-junosmcp_${version}_amd64 && JMCP_INSTALL_VERIFY_TOOLS=1 ./install.sh"

install.sh creates the jmcp service user, installs the binary and the systemd unit, and stops. The service will not start until it has an inventory. Then place the credentials and fix their modes:

pct push <vmid> devices.json /etc/jmcp/devices.json
pct push <vmid> id_ed25519   /etc/jmcp/id_ed25519
pct push <vmid> known_hosts  /etc/jmcp/known_hosts
pct exec <vmid> -- bash -lc '
    chown -R jmcp:jmcp /etc/jmcp
    chmod 0600 /etc/jmcp/devices.json /etc/jmcp/id_ed25519
    chmod 0644 /etc/jmcp/known_hosts
'

Mint a token (below), then start it:

pct exec <vmid> -- systemctl enable --now rust-junosmcp

The shipped unit binds 127.0.0.1:30030 and keeps its token store at /var/lib/jmcp/tokens.json. For remote clients, use an SSH tunnel or a TLS reverse proxy, or add site settings in a systemd drop-in as the HOW-TO shows.

To upgrade, read the CHANGELOG.md upgrade notes, then install the new tarball the same way. The installer does not restart the service, so do that yourself and check the version:

pct exec <vmid> -- systemctl try-restart rust-junosmcp
pct exec <vmid> -- /usr/local/bin/rust-junosmcp --version

The installer replaces the binary and the shipped unit, and leaves devices.json, tokens.json and known_hosts alone. Keep site settings in a drop-in, because edits to the shipped unit are lost.

Container creation, the site drop-in, verification and troubleshooting: docs/HOW-TO-SETUP-LXC.md. Release tarball verification: docs/REFERENCE.md.

Mint a token

Clients authenticate with a bearer token. The secret prints once and is stored hashed. Define jmcp for your install. The token paths are the same in both.

# LXC: run as the service user inside the guest.
jmcp() { pct exec <vmid> -- runuser -u jmcp -- /usr/local/bin/rust-junosmcp "$@"; }

# Docker: run from junos-docker/. No binary on the host is needed.
jmcp() {
  docker run --rm --entrypoint /usr/local/bin/rust-junosmcp \
    -v "$PWD/devices.json:/etc/jmcp/devices.json:ro" \
    -v "$PWD/state:/var/lib/jmcp" \
    "$image" "$@"
}

jmcp token add --tokens-file /var/lib/jmcp/tokens.json -f /etc/jmcp/devices.json \
    --name my-client --devices '*' --tools '*'

A wildcard --tools '*' grants read-only tools only. Name write tools explicitly or the caller gets insufficient_scope. After minting or revoking, signal the running server:

pct exec <vmid> -- systemctl kill -s HUP rust-junosmcp.service   # LXC
docker kill -s HUP junos-twoperson                               # Docker

Scopes, rotation and rescoping: Remote transport + auth.

Check it is up

The service listens on the guest's loopback, so on LXC run this inside the guest with pct exec <vmid> -- curl .... For Docker, run it on the host.

curl -s -o /dev/null -w '%{http_code}\n' -X POST http://127.0.0.1:30030/mcp \
     -H 'content-type: application/json' -d '{}'

401 is success: the transport is up and rejecting unauthenticated callers. 000 means nothing is listening. 421 means the allowed-host list is wrong.

2. Choose a safety mode

By default, every configuration write goes through a change set: one principal proposes it, a different principal approves it, and then it is applied. A principal is a bearer token. Choose how that rule applies to your deployment.

| | Two-person (default) | Lab mode (--lab-mode) | |---|---|---| | Flag | none | --lab-mode | | Who approves | a second principal | nobody; approved on creation | | Self-approval | refused | not needed | | Record | approver identity | approver: null, approval_waiver: "lab-mode" | | Use it for | anything real | a single-operator lab |

Two-person change control (default)

The flow is create_junos_change_set, then approve_junos_change_set, then apply_junos_change_set. A change set needs a second principal unless lab mode is on. The token that creates a change set cannot approve it. Plan, plan digest, drift detection and apply-time revalidation all run.

Set it up with two tokens. The token from Mint a token is read-only, so it can do neither job.

• A proposer token that names the change-set tools.
• An approver token held by a different person, with --actor-type human and the approve_junos_change_set tool. The server refuses approval from a non-human actor.

Mint both with the jmcp function from Mint a token:

jmcp token add --tokens-file /var/lib/jmcp/tokens.json -f /etc/jmcp/devices.json \
  --name proposer --actor-type agent --devices '*' \
  --tools get_junos_candidate_fingerprint,create_junos_change_set,get_junos_change_set_status,apply_junos_change_set,confirm_junos_change_set

jmcp token add --tokens-file /var/lib/jmcp/tokens.json -f /etc/jmcp/devices.json \
  --name alice --actor-type human --devices '*' \
  --tools approve_junos_change_set

Then signal the running server, as shown above.

Two tokens held by one person are not a second reviewer. To bind the approver to a real identity, use a verified approver (`--oidc-