convez.ai
MCP ServerSegurançaAvançado
Node804

PAN-OS MCP Server

Node804/node804-panos-mcp

Automação segura e econômica de firewalls Palo Alto via MCP

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP token-eficiente para firewalls Palo Alto Networks PAN-OS e Panorama, com 137 ferramentas de leitura, diagnóstico e gerenciamento. Implementa RBAC padrão-deny (apenas leitura por padrão) e verificação TLS obrigatória, reduzindo tokens em 40-70% comparado a alternativas.

Instalação

$npx convez-ai Node804/node804-panos-mcp

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
1
Forks
0
Acompanhando
0
Saúde
37%
Último commit
há 2 semanas
Versão
—
Issues abertas
1
Contribuidores
1

Casos de uso

  • Inspeção e troubleshooting de políticas de segurança (policy-match, NAT-match, FIB-lookup)
  • Gerenciamento de objetos de rede e tags (CRUD com controle de permissões)
  • Automação de commits e revert de configurações em modo admin
  • Agregação de logs e status de ameaças com redução de verbosidade

Veredito

Ferramenta robusta e production-ready para infraestrutura Palo Alto. Design inteligente com RBAC graduado e eficiência de tokens merece destaque, mas requer expertise em networking e administração de firewalls.

README

A tradução para o português deste README ainda está na fila.

PAN-OS MCP Server

CI PyPI Python License: MIT

A token-efficient MCP server for Palo Alto Networks PAN-OS firewalls and Panorama, built around three principles:

  1. Lean responses by default. Every list-returning tool exposes only the fields you actually need to answer the question. Verbose responses are opt-in. Typical 40-70% token reduction vs. dump-everything alternatives.
  2. Default-deny RBAC. With no environment configuration, the server exposes only read tools. Writes, commits, and raw API access require explicit opt-in via PANOS_MODE.
  3. TLS verification on by default. Self-signed certs require an explicit opt-out or a custom CA bundle — no silent man-in-the-middle exposure.

137 tools across system, diagnostics/troubleshooting, network, security, objects, NAT, user-ID, admin, VPN, Panorama, logs, threat, certificates, licenses, utility, and aggregation surfaces.

Permission Modes

ModeToolsDescription
read (default)89Read-only inspection, live troubleshooting (policy-match / NAT-match / FIB-lookup tests, session table, config diff, rule hit counts), and aggregation summaries. No writes.
standard99Read + object and tag CRUD (address objects, service objects, tags). No policy rules.
full130Standard + policy rule CRUD (security, NAT, PBF, QoS, decryption, static routes; Panorama pre/post rules). All writes go to candidate config — no live impact without commit.
admin137Full + commit, push, revert_config, and the raw set_config / delete_config / run_op_command escape hatches. This is the live-impact tier.

Tools above the active mode are not registered with the MCP server — the LLM never sees them, so there is nothing to call. Default mode is read.

Setup

Prerequisites

  • uv (recommended) — manages Python and dependencies for you
    • or Python 3.13+ with pip
  • A PAN-OS firewall or Panorama with the XML API enabled, plus an API key (see below)

Getting a PAN-OS API key

PAN-OS issues API keys via the /api/?type=keygen endpoint. The key inherits the admin account's RBAC — there is no separate "API role," so a read-only admin's key cannot push config even if PANOS_MODE=admin.

Best practice: create a dedicated service account (e.g. apiread) with a Superuser (read-only) dynamic role for PANOS_MODE=read. Issue a separate key from an account with write permissions for higher tiers.

curl:

curl -k -X POST "https://fw.example.com/api/?type=keygen" \
  --data-urlencode "user=apiread" \
  --data-urlencode "password=<password>"

PowerShell:

$body = @{ user = 'apiread'; password = '<password>' }
(Invoke-RestMethod -Method Post -Uri 'https://fw.example.com/api/?type=keygen' -Body $body -SkipCertificateCheck).response.result.key

Copy the returned <key> into PANOS_API_KEY. The same endpoint works against Panorama — point it at the Panorama hostname. Keys do not expire by default but are invalidated if the admin's password changes or the account is deleted.

Environment Variables

VariableRequiredDescription
PANOS_HOSTYes*Single-firewall hostname. *Not required in multi-firewall mode (see Multi-firewall configuration).
PANOS_API_KEYYes*Single-firewall API key. Stored in the OS keychain in multi-firewall mode.
PANOS_MODENoRBAC mode: read, standard, full, or admin. Default: read.
PANOS_TLS_VERIFYNotrue / false / 1 / 0 / yes / no. Default: true.
PANOS_TLS_CANoPath to a custom PEM CA bundle. Default: system trust store.
PANOS_FIREWALLS_CONFIGNoOverride path for firewalls.json. Default: ~/.config/panos-mcp/firewalls.json.
PANOS_AUDIT_LOGNoPath to a JSON-lines audit log. Every tool call is logged with sanitized args, success/error state, and timing. Disabled when unset.
PANOS_ENABLE_RAW_CONFIGNoRegister set_config / delete_config (also requires PANOS_MODE=admin). Default: false.
PANOS_ENABLE_RAW_OPSNoRegister run_op_command (also requires PANOS_MODE=admin). Default: false.
PANOS_RAW_XPATH_ALLOWNoComma-separated XPath prefixes that set_config / delete_config are restricted to. Default: unset (all non-denied).

The raw escape hatches are off by default and gated twice: they register only when their PANOS_ENABLE_RAW_* flag is truthy and PANOS_MODE=admin, and even then an internal denylist blocks destructive verbs and protected config subtrees. See tools/_guards.py.

Install

Option A — uv (recommended). No install step: uvx fetches the package from PyPI on first run and caches it. Pin the version so upgrades are deliberate:

uvx node804-panos-mcp==0.1.6

Option B — pip:

pip install node804-panos-mcp

Option C — from source (development):

git clone https://github.com/Node804/node804-panos-mcp.git
cd node804-panos-mcp
uv sync          # or: pip install -e ".[dev]"

Each option provides the node804-panos-mcp command and the panos_mcp Python module (runnable as python -m panos_mcp). The package pulls in its dependency node804-mcp-toolkit — shared RBAC, audit-logging, TLS, and lean-response utilities — automatically.

Until node804-mcp-toolkit is published to PyPI, install it from source first: pip install git+https://github.com/Node804/node804-mcp-toolkit.git

Claude Desktop

  1. Open your Claude Desktop config file:

    • Windows: %APPDATA%\Claude\claude_desktop_config.json
    • Mac: ~/Library/Application Support/Claude/claude_desktop_config.json
  2. Add the server under mcpServers (create the file if it doesn't exist):

{
  "mcpServers": {
    "PAN-OS": {
      "command": "uvx",
      "args": ["node804-panos-mcp==0.1.6"],
      "env": {
        "PANOS_HOST": "fw.example.com",
        "PANOS_API_KEY": "LUFRPT1xxx...",
        "PANOS_MODE": "read"
      }
    }
  }
}

If you installed with pip instead of uv, use "command": "python" with "args": ["-m", "panos_mcp"].

  1. Restart Claude Desktop — the server starts automatically when Claude needs it. It starts in read-only mode by default; raise PANOS_MODE to enable writes.

Claude Code (CLI)

claude mcp add node804-panos-mcp \
  -e PANOS_HOST=fw.example.com \
  -e PANOS_API_KEY=LUFRPT1xxx... \
  -e PANOS_MODE=read \
  -- uvx node804-panos-mcp==0.1.6

Verify with claude mcp list.

Verifying It Works

Once connected, ask your LLM:

  • "What's my access level?" → calls server_status, showing the active mode, live tool counts, TLS posture, and configured firewalls
  • "What firewalls are configured?" → calls list_firewalls, confirming the registry and which targets require an explicit firewall argument

If either fails, see Troubleshooting.

Token efficiency

Every list-returning tool accepts these parameters (from node804-mcp-toolkit):

ParameterDefaultEffect
verbosefalseWhen true, returns every field the underlying API exposes. Default returns only the fields most relevant to the tool's purpose.
fieldsnullExplicit projection. ["name", "action", "disabled"] returns exactly those fields. Overrides both verbose and the default whitelist.
pagination.limit100Max items per response. Hard ceiling: 1000.
pagination.offset0Skip count. Use with limit to page through inventories.
patternnullServer-side substring filter on the item's name field. Far cheaper than fetching the inventory and filtering client-side.

Responses are wrapped as {total, count, items} so the LLM knows when pagination truncated the result and whether to fetch more. Single-record tools (get_firewall_info, get_ha_status, etc.) accept verbose and fields.

Measured savings

Token counts below were measured against synthetic fixtures sized to mid-range deployments (100 security rules, 500 address objects). Encoding: cl100k_base (GPT-4 / Claude approximation). Every scenario is a regression-guarded test in tests/benchmark/ — the build fails if a future change widens a response shape past the budget.

ScenarioNaive approachTokensBetter approachTokensSaving
Find an address object by IPget_address_objects (dump 500)21,207find_address_object("10.0.0.5")88241× smaller
Inventory snapshotget_address_objects (dump 500)21,207count_objects_by_type27785× smaller
Audit security policyget_security_rules (verbose, 100 rules)19,627summarize_security_policy58338× smaller
Audit security policyget_security_rules (lean, 100 rules)5,095summarize_security_policy5888× smaller
Find rules matching a patternget_security_rules (lean dump)5,095find_rule_by_name("rule-001")24920× smaller
Filter rules by patternget_security_rules (no filter)5,095get_security_rules(pattern="rule-00")52310× smaller
Lean default vs verboseget_security_rules(verbose=true)19,627get_security_rules (default)5,09574% reduction

Run the benchmark suite yourself:

pytest -v -s -m benchmark

The headline number: a policy audit that would cost ~20K tokens via the naive "dump everything" approach costs ~60 tokens via summarize_security_policy.

Audit logging

Every tool invocation can be captured to a JSON-lines file:

export PANOS_AUDIT_LOG=/var/log/panos-mcp/audit.jsonl

Each line is one event:

{"ts":"2026-05-07T14:32:11.483Z","tool":"add_security_rule","mode":"full","firewall":"hq-fw","args":{"name":"block-tor","action":"deny"},"success":true,"duration_ms":412}

Sensitive keys (api_key, password, secret, token, auth) are redacted at any depth before logging. Strings over 2 KB are elided. Write failures warn once and never block tool execution.

The audit log is the only after-the-fact record for admin-mode operations (commit, set_config, run_op_command). Treat it accordingly.

TLS verification

Connections to PAN-OS are TLS-verified by default. For environments where the firewall presents a self-signed certificate or one signed by an internal CA:

# Option A: trust a custom CA bundle
export PANOS_TLS_CA=/etc/pki/internal-ca.pem

# Option B: disable verification (emits a startup warning)
export PANOS_TLS_VERIFY=false

The startup log reports the active posture:

PanOS TLS:   verify=ON (system trust store)
PanOS TLS:   verify=ON (custom CA via PANOS_TLS_CA)
PanOS TLS:   verify=OFF (PANOS_TLS_VERIFY=false)

Multi-firewall configuration

For environments managing multiple firewalls or Panorama instances, define them in ~/.config/panos-mcp/firewalls.json (override with PANOS_FIREWALLS_CONFIG=/path):

{
  "firewalls": [
    { "name": "hq",       "host": "hq.example.com" },
    { "name": "branch",   "host": "branch.example.com" },
    { "name": "panorama", "host": "panorama.example.com" }
  ]
}

API keys live in the OS keychain (macOS Keychain, Windows Credential Manager, Linux Secret Service via keyring). On first run, plaintext api_key fields in older configs auto-migrate to the keychain and the JSON is rewritten without them.

Linux headless servers without a keychain backend fall back to plaintext storage. The file is written with mode 0o600 (owner read/write only). The startup log emits a warning.

In multi-firewall mode, every tool that talks to a firewall requires an explicit firewall: <name> argument — no default is picked. Call list_firewalls to see configured targets and whether firewall is required.

Tools by category

Each cell shows how many tools that category contributes at that RBAC tier. A — means none. The Total column sums across tiers; the bottom row matches the tool counts reported by server_status.

CategoryReadStandardFullAdminTotal
System4———4
Diagnostics5———5
Network8—2—10
Security6—12—18
Objects & tags610——16
NAT1—4—5
User-ID3———3
Administrators3———3
VPN3———3
Panorama22—9—31
Logs5———5
Threat & content4———4
Certificates3—4—7
Licenses2———2
Utility4——15
Server diagnostic2———2
Aggregations8———8
Commit & raw API———66
Total89+10+31+7137

A few entries worth calling out by name:

  • Diagnostics (read) — test_security_policy_match, test_nat_policy_match, test_routing_fib_lookup, get_sessions, get_session_detail. Live troubleshooting via read-only <test> and session ops.
  • Utility — get_config_xpath, run_show_command, get_pending_changes, get_config_diff (read) for ad-hoc inspection and reviewing staged changes; run_op_command (admin) for the operational-command escape hatch.
  • Aggregations (read) — includes get_rule_hit_counts and unused_rules for usage-based rule cleanup.
  • Commit & raw API (admin) — commit, panorama_commit, panorama_push_to_devices, revert_config, set_config, delete_config.
  • Server diagnostic — server_status and list_firewalls. Always available, even in read mode.

Call server_status from your MCP client at runtime to see the active mode, live tool counts, TLS posture, audit destination, and the configured firewall registry.

Aggregation tools

Purpose-built summarization tools that replace "dump everything and grep" patterns with focused queries. Returning a structured answer is 10-20x cheaper in tokens than returning the full inventory and letting the LLM compute the same thing — the largest single source of token savings in the project.

ToolWhat it answers
find_rule_by_name(pattern, rule_types=None)Search rule names across security, NAT, PBF, and decryption rulebases. Case-insensitive substring match; each result is tagged with its rule type.
find_address_object(query)Find address objects by name substring or by IP membership. If the query parses as an IP/CIDR, returns objects whose ip-netmask, ip-range, or ip-wildcard value overlaps the query. Otherwise matches names.
count_rules_by_action(){"allow": 142, "deny": 38, "drop": 12} plus enabled/disabled counts. Replaces a 10K-token rule dump with a ~200-token snapshot.
summarize_security_policy()One-call policy audit: rule counts, action breakdown, any-any-any rules (worth reviewing), rules with logging disabled, rules without a profile group, and the set of zones referenced.
count_objects_by_type()Inventory snapshot: address objects by type (ip-netmask vs fqdn vs range), address groups (static vs dynamic), service objects by protocol, plus tag and application-filter totals.
get_rule_hit_counts(rule_base, vsys)Per-rule hit counts and last-hit timestamps (show rule-hit-count) — which rules actually carry traffic.
unused_rules(vsys, include_disabled=False)Security rules with zero hits, joined with the rulebase for disabled status — a ready cleanup worklist.

All are gated at Mode.READ — same tier as the underlying inventory reads.

Troubleshooting

SymptomCauseFix
No module named panos_mcpPackage not installedUse the uvx config (installs automatically), or run pip install node804-panos-mcp.
Server starts but tools return an auth errorInvalid or expired API keyRegenerate the key (see Getting a PAN-OS API key) and update your config. The key is invalidated if the admin's password changes.
TLS / certificate verification errors on connectFirewall presents a self-signed or internal-CA certSet PANOS_TLS_CA to your CA bundle, or PANOS_TLS_VERIFY=false to disable verification (emits a startup warning).
Tools you expect are missingMode is too restrictiveCheck server_status for the active mode, then raise PANOS_MODE (read → standard → full → admin).
Writes succeed but nothing changes on the firewallChanges are staged in candidate configCall commit (admin mode). Use get_pending_changes / get_config_diff to review what's staged first.
"firewall is required" errorsMulti-firewall mode with no targetPass firewall: <name>; run list_firewalls to see configured targets.
set_config / run_op_command not available in admin modeRaw escape hatches are off by defaultSet PANOS_ENABLE_RAW_CONFIG=true / PANOS_ENABLE_RAW_OPS=true and PANOS_MODE=admin.
A vsys-scoped query returns the wrong vsys's dataTools default to vsys1This release targets vsys1; for other virtual systems use get_config_xpath with an explicit vsys path until a vsys parameter lands.

Development

git clone https://github.com/Node804/node804-panos-mcp.git
cd node804-panos-mcp
pip install -e ".[dev]"          # or: uv sync --extra dev

pytest -v                                        # full test suite
pytest -v -m "not integration and not benchmark" # CI-equivalent
ruff check . && ruff format --check .            # lint + format
mypy src                                         # type check
node804-panos-mcp                                # boot the server

node804-mcp-toolkit installs automatically as a dependency. Until it's on PyPI, install it from source first (see Install).

Acknowledgments

Built on pan-os-python — Palo Alto Networks' official Python SDK. The PAN-OS object model and API client behavior come from there; this project provides the MCP wrapper, response shaping, RBAC, and audit infrastructure on top.

AI-Assisted Development

Portions of this project — including code, tests, and documentation — were developed with the assistance of generative AI (Anthropic's Claude, ChatGPT). All changes are human-reviewed before merge and exercised by the automated test suite, but as with any software, review the code and test against a non-production firewall or Panorama before trusting it with write access (standard mode or above) to a live device.

License

MIT

Ver o original no GitHub

Bom para

Relacionados