rustpanosmcp

<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-panosmcp</h1>

<p align="center"><strong>Async Rust Model Context Protocol server for Palo Alto Networks PAN-OS firewalls</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 Palo Alto Networks. Product names and trademarks are used only to identify the systems with which the software interoperates.

The repository contains the v0.16.2 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`](https://github.com/mechubsec/mecmcp) and [`mecmcp-audit`](https://github.com/mechubsec/mecmcp) 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](PLAN.md). Security
boundaries and release-blocking controls are tracked in
[THREAT_MODEL.md](THREAT_MODEL.md).

## Workspace

```text
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](https://github.com/mechubsec/rustpanosmcp/releases). Assets follow the pattern `rust-panosmcp-v0.16.2-x86_64-unknown-linux-gnu.tar.gz` with a corresponding `.sha256` file.

```bash
# Download and verify
curl -LO https://github.com/mechubsec/rustpanosmcp/releases/download/v0.16.2/rust-panosmcp-v0.16.2-x86_64-unknown-linux-gnu.tar.gz
curl -LO https://github.com/mechubsec/rustpanosmcp/releases/download/v0.16.2/rust-panosmcp-v0.16.2-x86_64-unknown-linux-gnu.tar.gz.sha256
sha256sum -c rust-panosmcp-v0.16.2-x86_64-unknown-linux-gnu.tar.gz.sha256

# Extract
tar xzf rust-panosmcp-v0.16.2-x86_64-unknown-linux-gnu.tar.gz
cd rust-panosmcp-v0.16.2

# 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/](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](docs/HOW-TO-SETUP-LXC.md).

```bash
# Download and verify
curl -LO https://github.com/mechubsec/rustpanosmcp/releases/download/v0.16.2/rust-panosmcp-v0.16.2-x86_64-unknown-linux-gnu.tar.gz
curl -LO https://github.com/mechubsec/rustpanosmcp/releases/download/v0.16.2/rust-panosmcp-v0.16.2-x86_64-unknown-linux-gnu.tar.gz.sha256
sha256sum -c rust-panosmcp-v0.16.2-x86_64-unknown-linux-gnu.tar.gz.sha256

# Extract and run the installer
tar xzf rust-panosmcp-v0.16.2-x86_64-unknown-linux-gnu.tar.gz
cd rust-panosmcp-v0.16.2
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](.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](docs/HOW-TO-SETUP-DOCKER.md).

```bash
# 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](docs/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`:

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

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

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

```bash
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](config/devices.example.json), keep the
real inventory out of Git, and provide the referenced environment secret:

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

`