rustsdcmcp

<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">rustsdcmcp</h1>

<p align="center"><strong>Async Rust Model Context Protocol server for HPE Juniper Security Director Cloud</strong><br>
<em>a mechub project — sovereign network-security automation</em></p>

> **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`](https://github.com/mechubsec/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 **78 MCP tools** (v0.3.1 and `main`; v0.2.0 shipped 74): 60 bounded read
tools and 18 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`](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`](docs/sdc-api/README.md#still-unverified).

## Download

The current release, [`v0.3.1`](https://github.com/mechubsec/rustsdcmcp/releases/tag/v0.3.1),
attaches a checksummed, cosign-signed LXC install tarball
(`rustsdcmcp_0.3.1_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.3.1` 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:

```console
approved_commit=$(git rev-parse v0.3.1^{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:

```console
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"
```

## Docker quick start

For running the published container image, see [HOW-TO-SETUP-DOCKER.md](docs/HOW-TO-SETUP-DOCKER.md).

## Debian 13 LXC quick start

For building an LXC from scratch, see [HOW-TO-SETUP-LXC.md](docs/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.3.1` release tarball (or build one from approved
source — see [Build from approved source](#build-from-approved-source) above)
and install the verified package:

```bash
set -euo pipefail
mapfile -t archives < <(find . -maxdepth 1 -type f -name 'rustsdcmcp_0.3.1_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:

```bash
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.

```console
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:

```console
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`](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 automati