rust-panosmcp

用于 Palo Alto Networks PAN-OS 防火墙的异步 Rust Model Context Protocol 服务器
一个 mechub 项目 — 主权网络安全自动化

本仓库包含 v0.4.0 版本：一个具有结构化审计日志、受保护的 PAN-OS 候选配置生命周期、以及强化版发布打包的 bearer 保护型服务器，其身份验证和审计由共享的 [`mecmcp-auth`](https://github.com/fastrevmd-lab/mecmcp) 和 [`mecmcp-audit`](https://github.com/fastrevmd-lab/mecmcp) crate 提供。 本项目的目标是打造一个小巧、快速、面向生产环境的服务器，并具备与 `rust-junosmcp` 相同的安全态势：bearer token 身份验证、基于 token 的设备和工具作用域、TLS、严格的远程绑定拒绝规则、有限的输入和输出、可审计的更改操作，以及高效的连接复用。 架构和交付计划位于 [PLAN.md](PLAN.md)。安全边界和发布阻断控制在 [THREAT_MODEL.md](THREAT_MODEL.md) 中跟踪。 ## 工作区 ``` 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 ``` ## 快速开始 ### 安装 从三种安装路径中选择一种： #### 发布包 (Linux x86_64) 从 [GitHub releases](https://github.com/fastrevmd-lab/rustpanosmcp/releases) 下载最新版本。资产遵循 `rust-panosmcp-v0.4.0-x86_64-unknown-linux-gnu.tar.gz` 模式，并附带相应的 `.sha256` 文件。 ``` # 下载并验证 curl -LO https://github.com/fastrevmd-lab/rustpanosmcp/releases/download/v0.4.0/rust-panosmcp-v0.4.0-x86_64-unknown-linux-gnu.tar.gz curl -LO https://github.com/fastrevmd-lab/rustpanosmcp/releases/download/v0.4.0/rust-panosmcp-v0.4.0-x86_64-unknown-linux-gnu.tar.gz.sha256 sha256sum -c rust-panosmcp-v0.4.0-x86_64-unknown-linux-gnu.tar.gz.sha256 # 解压 tar xzf rust-panosmcp-v0.4.0-x86_64-unknown-linux-gnu.tar.gz cd rust-panosmcp-v0.4.0 # 安装二进制文件和 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 # 创建服务用户和目录，然后启动 sudo systemd-sysusers sudo systemd-tmpfiles --create sudo systemctl daemon-reload sudo systemctl enable --now rust-panosmcp ``` 这将创建一个专用的 `rust-panosmcp` 系统用户，并配置 `/etc/rust-panosmcp`（配置目录，由 root 拥有）和 `/var/lib/rust-panosmcp`（状态目录）。解压后的压缩包在 `config/` 目录中包含配置示例 —— 在启动之前，请使用 `devices.example.json` 和 `tokens.example.json` 作为 `/etc/rust-panosmcp` 下的起始模板。有关单元详细信息，请参阅 [packaging/systemd/](packaging/systemd/)。 #### LXC (Debian 13) 对于 Proxmox 或独立 systemd-nspawn 上专用的非特权 LXC 容器，发布包包含一个幂等安装程序，可自动执行上述手动序列。 ``` # 下载并验证 curl -LO https://github.com/fastrevmd-lab/rustpanosmcp/releases/download/v0.4.0/rust-panosmcp-v0.4.0-x86_64-unknown-linux-gnu.tar.gz curl -LO https://github.com/fastrevmd-lab/rustpanosmcp/releases/download/v0.4.0/rust-panosmcp-v0.4.0-x86_64-unknown-linux-gnu.tar.gz.sha256 sha256sum -c rust-panosmcp-v0.4.0-x86_64-unknown-linux-gnu.tar.gz.sha256 # 解压并运行安装程序 tar xzf rust-panosmcp-v0.4.0-x86_64-unknown-linux-gnu.tar.gz cd rust-panosmcp-v0.4.0 sudo packaging/lxc/install.sh # 配置 inventory 并生成第一个 token sudo vi /etc/rust-panosmcp/devices.json sudo rust-panosmcp token add \ --tokens-file /etc/rust-panosmcp/tokens.json \ --name initial-token \ --devices fw-example \ --tools list_devices,gather_device_facts,execute_panos_op,get_panos_config # 启动服务 sudo systemctl enable --now rust-panosmcp.service ``` 该安装程序通过 `systemd-sysusers` 和 `systemd-tmpfiles` 创建 `rust-panosmcp` 用户和目录，安装二进制文件和单元，创建模式为 0600 的空 `tokens.json`，并且如果 `/var/lib/rust-panosmcp/mutation-state.json` 已存在，则永远不会覆盖它（变更集审计追踪）。端点默认监听 `http://127.0.0.1:30031/mcp`。有关环境变量覆盖和升级行为，请参见 `packaging/lxc/install.sh`。 #### Docker / GHCR 每次发布标签时，预构建的镜像都会发布到 `ghcr.io/fastrevmd-lab/rust-panosmcp`。有关构建流水线，请参见 [.github/workflows/release-image.yml](.github/workflows/release-image.yml)。 ``` # 拉取镜像 docker pull ghcr.io/fastrevmd-lab/rust-panosmcp:latest # 使用挂载的 config 运行（参见 compose.example.yaml） docker run --rm -i \ -v "$PWD/devices.json:/etc/rust-panosmcp/devices.json:ro" \ -v "$PWD/tokens.json:/etc/rust-panosmcp/tokens.json:ro" \ ghcr.io/fastrevmd-lab/rust-panosmcp:latest ``` 仓库中包含一个 `compose.example.yaml` 文件。 #### 从源码构建 需要 Rust 1.88 或更高版本 (MSRV)。 ``` git clone https://github.com/fastrevmd-lab/rustpanosmcp.git cd rustpanosmcp cargo build --release --locked ./target/release/rust-panosmcp --version ``` ### 运行 (stdio) 从 [config/devices.example.json](config/devices.example.json) 开始配置，将实际清单排除在 Git 之外，并提供所引用的环境密钥： ``` export PANOS_LAB_API_KEY='runtime-secret' cargo run --locked --release -- --device-mapping /absolute/path/devices.json ``` ### 运行（带身份验证的 streamable-http） 首先生成一个最小权限的 token，然后启动 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 ``` 安全地捕获第一个命令的标准输出：这是新的 bearer 密钥的唯一显示。有关 token 轮换、重新加载、拒绝规则、反向代理部署和所有安全默认设置，请参见 [docs/PHASE2_OPERATIONS.md](docs/PHASE2_OPERATIONS.md)。第一阶段的清单和防火墙 TLS 详细信息保留在 [docs/PHASE1_OPERATIONS.md](docs/PHASE1_OPERATIONS.md)。 ## 状态 第一阶段实现了经过验证的清单和密钥提供程序、带有系统根证书/自定义 CA/确切叶证书锁定的严格 HTTPS、池化的异步 PAN-OS XML API 调用、类型化错误、超时、取消、输出上限以及每设备信号量。 第二阶段添加了仅摘要的 bearer token、确切的设备/工具作用域、原子化的清单/token 重载、TLS Streamable HTTP、Host/Origin 验证、有限的请求主体、IP/token 速率限制以及审计安全的请求追踪。两种 transport 都公开了四个只读工具：`list_devices`、`gather_device_facts`、`execute_panos_op` 和 `get_panos_config`。 第三阶段添加了可选的候选指纹、严格的 XPath 策略、PAN-OS 配置锁、每设备序列化、阶段/diff/完全验证、admin 作用域的部分提交/恢复、作业调节以及结构化的突变审计。写入工具需要明确的 token 作用域；`*` 保持只读。 第四阶段添加了摘要锁定的非 root 的 Distroless 镜像、强化的 systemd unit、只读部署指南、PAN-OS 发布系列矩阵、五个解析器模糊测试目标、逐字节可复现的存档、安全/运行手册文档以及发布的 Rust/Python 测量结果。 v0.2 添加了持久化的多操作变更集、特定于 token 的 XPath/操作授权和过期、规范端点序列化，以及绑定到确切所有者/设备/指纹/操作摘要的独立批准。批准的变更集在一个 PAN-OS 配置锁下应用，如果后续操作失败，则自动由 admin 恢复。然后，它们使用现有的 diff、完全验证、提交或丢弃生命周期。请参见 [docs/V0.2_CHANGE_SETS.md](docs/V0.2_CHANGE_SETS.md)。 v0.2.1 将 PAN-OS 配置锁释放变为已确认的状态转换：提交/丢弃记录仅在设备接受解锁后清除 `config_lock_held`，而失败解锁将作为 `indeterminate` 持久保存以进行显式调节。它还在 [docs/V0.2.1_ACCEPTANCE.md](docs/V0.2.1_ACCEPTANCE.md) 中记录了默认信任的 TLS 和实验室推广证据。 v0.2.2 更新了维护的 Rust 依赖图和 GitHub Actions，同时保留了 v0.2.1 的 PAN-OS 工具、授权、清单和突变状态接口。发布的发行版和受保护的实验室推广证据位于 [docs/V0.2.2_ACCEPTANCE.md](docs/V0.2.2_ACCEPTANCE.md)。Multi-vsys、HA 和 Panorama 的工作仍然推迟。 v0.3.0 将身份验证转移到了共享的 [`mecmcp-auth`](https://github.com/fastrevmd-lab/mecmcp) crate 上，退役了本仓库自己的 token、存储和 token 文件实现，转而采用一个共享的、经过独立测试的 crate。PAN-OS 工具接口、授权作用域、清单和突变状态接口保持不变。操作员可见的更改有两点：`tokens.json` 必须是模式 0600，否则服务器拒绝启动；并且磁盘上的信封版本现在在写入时会被保留，因此本版本涉及的文件对于以前的版本仍然可读。升级步骤请参见 [CHANGELOG.md](CHANGELOG.md)。 完整的 HTTPS 模拟、MCP 端到端以及显式配置的 `panosvm` 实验室防火墙验收套件均已通过。第一阶段已完成；可复现的证据记录在 [docs/PHASE1_ACCEPTANCE.md](docs/PHASE1_ACCEPTANCE.md) 中。 第二阶段验收证据记录在 [docs/PHASE2_ACCEPTANCE.md](docs/PHASE2_ACCEPTANCE.md) 中。配置突变验收位于 [docs/PHASE3_ACCEPTANCE.md](docs/PHASE3_ACCEPTANCE.md)，操作员要求位于 [docs/PHASE3_OPERATIONS.md](docs/PHASE3_OPERATIONS.md)。 第四阶段发布证据位于 [docs/PHASE4_ACCEPTANCE.md](docs/PHASE4_ACCEPTANCE.md)。生产部署、轮换、备份/恢复和升级由 [docs/OPERATIONS.md](docs/OPERATIONS.md) 涵盖；另请参见 [docs/COMPATIBILITY.md](docs/COMPATIBILITY.md)、[docs/BENCHMARKS.md](docs/BENCHMARKS.md) 和 [SECURITY.md](SECURITY.md)。 ## MCP 工具参考 服务器公开了 15 个 MCP 工具，按操作类型分组： ### 只读工具 - **`list_devices`** — 列出已授权的 PAN-OS 设备和安全元数据；永远不返回 API 密钥。 - **`gather_device_facts`** — 从授权设备收集主机名、型号、序列号、版本、管理 IP 和正常运行时间。 - **`execute_panos_op`** — 在授权设备上执行根植于 `` 的只读 PAN-OS XML 命令，并带有输出上限。 - **`get_panos_config`** — 在授权设备上读取经过验证的 `/config` XPath 处的运行中或候选 PAN-OS 配置。 ### 候选生命周期工具（突变） - **`get_candidate_fingerprint`** — 返回所有操作员授权的候选子树上的 SHA-256 指纹。 - **`stage_panos_config`** — 使用预期的指纹暂存一个受策略限制的 PAN-OS 候选集/删除操作。 - **`diff_panos_candidate`** — 为确切暂存的候选指纹返回有限的 PAN-OS 更改摘要。 - **`validate_panos_candidate`** — 验证暂存的候选操作，并使相同指纹有资格进行提交。 - **`commit_panos_candidate`** — 使用确切的候选指纹仅提交已成功验证的操作。 - **`discard_panos_candidate`** — 通过 admin 作用域的部分候选恢复来丢弃暂存操作。 - **`get_panos_operation`** — 返回拥有的 PAN-OS 候选生命周期操作的安全状态。 ### 变更集工具 (v0.2+) - **`create_panos_change_set`** — 在清单和 token XPath/操作作用域下计划并持久化 1-64 个有序的 PAN-OS 候选操作。 - **`approve_panos_change_set`** — 批准未过期的确切变更集摘要；拒绝自我批准。 - **`get_panos_change_set`** — 返回确切的操作、摘要、批准、过期和操作状态，以供审查或恢复。 - **`apply_panos_change_set`** — 在一个端点/配置锁下应用独立批准的确切变更集，恢复部分失败的操作。 写入工具需要明确的 token 作用域；通配符 `*` 授权保持只读。 ## 配置 [config/](config/) 中的三个示例文件演示了配置接口： - **[`devices.example.json`](config/devices.example.json)** — 带有身份验证、TLS 验证模式（系统根证书、自定义 CA 或确切叶证书锁定）、设备级并发限制以及用于候选操作的可选 admin 覆盖的设备清单。 - **[`tokens.example.json`](config/tokens.example.json)** — Bearer token 存储结构：仅摘要存储、基于 token 的设备和工具允许列表、可选的突变授权（XPath 根、允许的操作）以及过期时间戳。 - **[`devices.mutation.example.json`](config/devices.mutation.example.json)** — 展示突变根配置和 admin 作用域候选工作流字段的清单变体。 清单文件绝不保存内联凭据：每个设备的 `api_key` 都是一个引用 — `{"type": "env", "name": "VAR_NAME"}` 用于环境变量，或 `{"type": "file", "path": "/protected/path"}` 用于模式受限的密钥文件。 ## 审计日志 v0.4.0 通过共享的 [`mecmcp-audit`](https://github.com/fastrevmd-lab/mecmcp) crate 引入了结构化的审计日志。每次工具调用都会发出一个事件，其中包含调用者归属、目标设备、结果和执行持续时间。 变更集生命周期审计提供了独立的批准证据：`approve_panos_change_set` 事件同时包含变更集 ID 和指纹摘要，证明第二个主体审查了后来通过 `apply_panos_change_set` 应用的确切摘要。 ### 审计配置标志 - **`--audit-format {json|pretty}`** — 选择 `json`（默认，机器可解析）或 `pretty`（人类可读）。 - **`--audit-log-file `** — 将审计事件写入文件路径。 - **`--audit-journald`** — 将审计事件发送到 systemd journal。 - **`--audit-redact`** — HMAC 伪匿名化已声明的字段（设备名称、调用者身份），以便日志可以发送到 SIEM，而不会泄漏操作标识符。 - **`--audit-hmac-key-file `** — 用于 HMAC 密钥的路径；启用 `--audit-redact` 时必需。 所有审计目标都是可选的，并且可以组合使用。如果未指定审计目标，则不会发出审计事件。 ## 安全性 有关完整的覆盖范围，请参见 [REAT_MODEL.md](THREAT_MODEL.md) 和 [SECURITY.md](SECURITY.md)。关键点： - **HTTP 需要身份验证** — 带有 SHA-256 摘要存储的 bearer token；不保留明文密钥。 - **默认仅支持回环** — 环回外的 HTTP 需要 TLS 或显式的 `--allow-insecure-bind`；环回外的 TLS 需要 `--allowed-host`。 - **TLS 验证始终开启** — 系统根证书、自定义 CA bundle 或确切的叶证书锁定；没有首次使用信任 (TOFU) 或禁用的验证。 - **有限的 I/O** — 输出上限（默认为 512 KiB，最大为 5 MiB）、请求主体限制（默认为 1 MiB）、所有 PAN-OS 调用的超时。 - **可审计的突变** — 候选操作按设备序列化，记录主体和指纹，在验证后需要显式提交，并持久化锁/作业状态以进行恢复。 ## CLI 参考 ``` Secure, async MCP server for PAN-OS firewalls Usage: rust-panosmcp [OPTIONS] [COMMAND] Commands: token Manage the digest-only bearer-token store state Perform offline recovery on the private mutation-state file help Print this message or the help of the given subcommand(s) Options: -f, --device-mapping Validated JSON device inventory [default: devices.json] -t, --transport MCP transport [default: stdio] [possible values: stdio, streamable-http] -H, --host Numeric bind address for Streamable HTTP [default: 127.0.0.1] -p, --port TCP port for Streamable HTTP [default: 30031] --tokens-file Absolute digest-only bearer-token file path --state-file Absolute private JSON file for persistent change-set and operation state --tls-cert Absolute PEM certificate path; requires `--tls-key` --tls-key Absolute PEM private-key path; requires `--tls-cert` --allow-no-auth Disable bearer auth for a loopback-only development listener --allow-insecure-bind Permit a non-loopback plaintext listener behind a trusted TLS proxy --allowed-host Additional accepted HTTP Host authority. Repeat for multiple values --allowed-origin Accepted browser Origin URL. Repeat for multiple values --ip-rate-per-minute Per-source-IP requests allowed per rolling minute window [default: 120] --token-rate-per-minute Per-authenticated-token requests allowed per rolling minute window [default: 240] --request-body-limit Maximum Streamable HTTP request body in bytes [default: 1048576] -h, --help Print help -V, --version Print version Token subcommands: add Mint a token, store only its digest, and print the secret once list List token names and scopes without secrets or digests revoke Revoke a named token rotate Replace a token secret while preserving its scopes State subcommands: resolve Mark an indeterminate operation terminal after manual PAN-OS reconciliation ``` ## 验证 ``` cargo fmt --all -- --check cargo clippy --workspace --all-targets --all-features -- -D warnings cargo test --workspace --locked cargo check --manifest-path fuzz/Cargo.toml --bins --locked scripts/verify-packaging.sh ``` 使用 `scripts/build-release.sh` 创建确定性的发布存档，或者编译两次并使用 `scripts/verify-reproducible-build.sh` 要求字节一致性。容器/systemd 安装记录在操作员运行手册中。 ## 许可证 根据 [MIT](LICENSE) 授权。

_{a mechub project · deterministic decides · the model explains · a human approves
github.com/fastrevmd-lab}

标签：Docker 部署, Rust, 可视化界面, 底层编程, 异步编程, 模型上下文协议(MCP), 网络安全, 网络流量审计, 网络运维, 请求拦截, 通知系统, 防火墙管理, 隐私保护