rust-panosmcp

rust-panosmcp

Async Rust Model Context Protocol server for Palo Alto Networks PAN-OS firewalls

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 Palo Alto Networks. Product names and trademarks are used only to identify the systems with which the software interoperates.

The repository contains the v0.17.0 release: a bearer-protected server with structured audit logging, guarded PAN-OS candidate configuration lifecycle, and hardened release packaging, with authentication and auditing provided by the shared mecmcp-auth and mecmcp-audit crates.

The project goal is a small, fast, production-oriented server with the same security posture as rust-junosmcp: bearer-token authentication, per-token device and tool scopes, TLS, strict remote-bind refusal rules, bounded input and output, auditable change operations, and efficient connection reuse.

The architecture and delivery plan are in PLAN.md. Security boundaries and release-blocking controls are tracked in THREAT_MODEL.md.

Workspace

rust-panosmcp/          # MCP binary and stdio adapter

rust-panosmcp-auth/ # bearer and secret-handling foundations rust-panosmcp-core/ # inventory, PAN-OS client, validation, tool logic config/ # secret-free inventory examples docs/ # operator guidance and phase notes fuzz/ # isolated cargo-fuzz workspace packaging/ # distroless/container and systemd assets scripts/ # release, matrix, fuzz, and benchmark gates

Quick start

Installation

Choose one of three install paths:

Release tarball (Linux x86_64)

Download the latest release from GitHub releases. Assets follow the pattern rust-panosmcp-v0.17.0-x86_64-unknown-linux-gnu.tar.gz with a corresponding .sha256 file.

# Download and verify

curl -LO https://github.com/mechubsec/rustpanosmcp/releases/download/v0.17.0/rust-panosmcp-v0.17.0-x86_64-unknown-linux-gnu.tar.gz curl -LO https://github.com/mechubsec/rustpanosmcp/releases/download/v0.17.0/rust-panosmcp-v0.17.0-x86_64-unknown-linux-gnu.tar.gz.sha256 sha256sum -c rust-panosmcp-v0.17.0-x86_64-unknown-linux-gnu.tar.gz.sha256

Extract

tar xzf rust-panosmcp-v0.17.0-x86_64-unknown-linux-gnu.tar.gz cd rust-panosmcp-v0.17.0

Install the binary and systemd assets

sudo install -m 0755 bin/rust-panosmcp /usr/local/bin/rust-panosmcp sudo install -m 0644 packaging/systemd/rust-panosmcp.sysusers /usr/lib/sysusers.d/rust-panosmcp.conf sudo install -m 0644 packaging/systemd/rust-panosmcp.tmpfiles /usr/lib/tmpfiles.d/rust-panosmcp.conf sudo install -m 0644 packaging/systemd/rust-panosmcp.service /etc/systemd/system/rust-panosmcp.service

Create the service user and directories

sudo systemd-sysusers sudo systemd-tmpfiles --create

Generate the HMAC key for audit redaction (required).

Guarded: NEVER overwrite an existing key. The key is what makes an HMAC-redacted

device identifier comparable across audit history, so replacing it silently

breaks correlation with every record already written. These steps are safe to

re-run during an upgrade only because of this guard.

sudo sh -c '[ -f /etc/rust-panosmcp/audit-hmac.key ] || head -c 32 /dev/urandom | base64 > /etc/rust-panosmcp/audit-hmac.key' sudo chmod 0600 /etc/rust-panosmcp/audit-hmac.key sudo chown rust-panosmcp:rust-panosmcp /etc/rust-panosmcp/audit-hmac.key

Start the service

sudo systemctl daemon-reload sudo systemctl enable --now rust-panosmcp

This creates a dedicated rust-panosmcp system user and provisions /etc/rust-panosmcp (config, root-owned) and /var/lib/rust-panosmcp (state). The HMAC key at /etc/rust-panosmcp/audit-hmac.key is required for device-redaction in audit logs — the service will not start without it. The extracted archive includes configuration examples in config/ — use devices.example.json and tokens.example.json as starting templates under /etc/rust-panosmcp before starting. See packaging/systemd/ for unit details.

LXC (Debian 13)

For a dedicated unprivileged LXC container on Proxmox or standalone systemd-nspawn, the release tarball includes an idempotent installer that automates the manual sequence above. For a complete setup guide including container creation, see HOW-TO-SETUP-LXC.md.

# Download and verify

curl -LO https://github.com/mechubsec/rustpanosmcp/releases/download/v0.17.0/rust-panosmcp-v0.17.0-x86_64-unknown-linux-gnu.tar.gz curl -LO https://github.com/mechubsec/rustpanosmcp/releases/download/v0.17.0/rust-panosmcp-v0.17.0-x86_64-unknown-linux-gnu.tar.gz.sha256 sha256sum -c rust-panosmcp-v0.17.0-x86_64-unknown-linux-gnu.tar.gz.sha256

Extract and run the installer

tar xzf rust-panosmcp-v0.17.0-x86_64-unknown-linux-gnu.tar.gz cd rust-panosmcp-v0.17.0 sudo packaging/lxc/install.sh

Configure the inventory and mint the first token

sudo vi /etc/rust-panosmcp/devices.json sudo rust-panosmcp token add \ --tokens-file /var/lib/rust-panosmcp/tokens.json \ --name initial-token \ --devices fw-example \ --tools list_devices,gather_device_facts,execute_panos_op,get_panos_config

Start the service

sudo systemctl enable --now rust-panosmcp.service

The installer creates the rust-panosmcp user and directories via systemd-sysusers and systemd-tmpfiles, installs the binary and unit, creates an empty tokens.json with mode 0600, and never overwrites /var/lib/rust-panosmcp/mutation-state.json if it exists (change-set audit trail). The endpoint listens on http://127.0.0.1:30031/mcp by default. See packaging/lxc/install.sh for environment-variable overrides and upgrade behavior.

Docker / GHCR

Prebuilt images are published to ghcr.io/mechubsec/rustpanosmcp on every release tag. See .github/workflows/release-image.yml for the build pipeline. For a complete setup guide including both two-person and lab modes, see HOW-TO-SETUP-DOCKER.md.

# Pull the image

docker pull ghcr.io/mechubsec/rustpanosmcp:latest

The default CMD binds 127.0.0.1:30031 *inside* the container, so a bare docker run with no -p and no --host/--allowed-host/--allowed-origin starts cleanly but is not reachable from outside the container. Follow HOW-TO-SETUP-DOCKER.md for a working two-person or lab-mode docker run invocation (including the port publish and the flags the baked-in ENTRYPOINT already supplies) or use the included compose.example.yaml.

Run with Docker (stdio)

For MCP clients that launch a server over stdin/stdout, prepare an inventory with the same shape as config/devices.example.json:

{

"version": 1, "policy": { "mode": "allowlist", "allow": ["show system info", "show interface all"] }, "devices": [ { "name": "panos-demo", "endpoint": "https://panos-demo.example.net", "vsys": "vsys1", "api_key": { "type": "env", "name": "PANOS_DEMO_API_KEY" }, "tags": ["lab", "read-only"] } ] }

Export the API-key variable before launching the container. This passthrough form keeps the key out of the command line, but Docker daemon access can still expose environment values through inspection. For stricter handling, use the file-based API-key form ({"type":"file","path":"/protected/path"}) documented in the configuration section below and mount that file read-only with mode 0600.

export PANOS_DEMO_API_KEY=replace-with-runtime-secret

Make the mounted inventory and state files readable and writable only by the container user (uid:gid 65532:65532); secret-bearing files must have mode 0600. Stdio is unauthenticated at the process boundary: the launcher can use every device in the mounted inventory and every tool, so scope access by limiting that inventory and using a read-only PAN-OS API role. The state directory must be writable because the server creates its audit state there.

mkdir -p state

chmod 0600 devices.json sudo chown 65532:65532 devices.json state

docker run --rm -i \ --user 65532:65532 \ -e PANOS_DEMO_API_KEY \ -v "$PWD/devices.json:/etc/rust-panosmcp/devices.json:ro" \ -v "$PWD/state:/var/lib/rust-panosmcp" \ ghcr.io/mechubsec/rustpanosmcp:0.15.0 \ --transport stdio

The image ENTRYPOINT already supplies the config, token, state, and audit-key paths, so do not repeat those flags after the image name. The token path is only used by HTTP. This invocation leaves HTTP and listener TLS off: supplying --transport stdio replaces the image CMD, including its HTTP bind and port flags. Connections to the firewall still use HTTPS according to the inventory's TLS trust settings.

Build from source

Requires Rust 1.89 or newer (MSRV).

git clone https://github.com/mechubsec/rustpanosmcp.git

cd rustpanosmcp cargo build --release --locked ./target/release/rust-panosmcp --version

Run (stdio)

Start from config/devices.example.json, keep the real inventory out of Git, and provide the referenced environment secret:

export PANOS_LAB_API_KEY='runtime-secret'

cargo run --locked --release -- --device-mapping /absolute/path/devices.json

Run (streamable-http with auth)

First mint a least-privilege token, then start the TLS Streamable HTTP transport:

cargo run --locked --release -- \

--device-mapping /etc/rust-panosmcp/devices.json \ token add \ --tokens-file /etc/rust-panosmcp/tokens.json \ --name read-only-client \ --devices fw-example \ --tools list_devices,gather_device_facts,execute_panos_op,get_panos_config

cargo run --locked --release -- \ --device-mapping /etc/rust-panosmcp/devices.json \ --transport streamable-http \ --host 0.0.0.0 --port 30031 \ --tokens-file /etc/rust-panosmcp/tokens.json \ --tls-cert /etc/rust-panosmcp/server.crt \ --tls-key /etc/rust-panosmcp/server.key \ --allowed-host mcp.example.net \ --allowed-origin https://client.example.net

Capture the first command's stdout securely: that is the only display of the new bearer secret. See docs/PHASE2_OPERATIONS.md for token rotation, reload, refusal rules, reverse-proxy deployment, and all security defaults. Phase 1 inventory and firewall TLS details remain in docs/PHASE1_OPERATIONS.md.

Next: [Learn the reader, writer, and reviewer MCP role

workflow](docs/MCP_ROLE_WORKFLOW.md).

Status

Phase 1 implemented validated inventory and secret providers, strict HTTPS with system roots/custom CA/exact leaf pinning, pooled async PAN-OS XML API calls, typed errors, timeouts, cancellation, output caps, and a per-device semaphore. Phase 2 added digest-only bearer tokens, exact device/tool scopes, atomic inventory/token reload, TLS Streamable HTTP, Host/Origin validation, bounded request bodies, IP/token rate limits, and audit-safe request tracing. Both transports share the same 28 tools described in MCP tools reference below; wildcard * token scopes reach only the 17 read-only ones (list_devices, gather_device_facts, execute_panos_op, get_panos_config, list_panos_entries, get_panos_entry_digest, list_panorama_device_groups, list_panorama_templates, get_panorama_push_status, list_panos_rulebase_entries, `