Getting Started

This guide walks you through setting up the Palo Alto Panorama Integration for NetBox.

• Prerequisites
• Host Requirements
  • System
  • Network
• Panorama Setup
  • Choose Panorama credentials
• NetBox Setup
  • Generate Diode Client Credentials
• Agent Setup and Configuration
  • Step 1: Authenticate to the NetBox Labs Image Registry
  • Step 2: Configure the Agent
  • Scope Configuration
  • Bootstrap Mode (First-Time Setup)
  • Optional - Dry Run Mode
  • Step 3: Run the Agent
    • Method 1: Set Environment Variables Manually
    • Method 2: Use a .env File (Recommended)
• Expected Output
• View and Apply Discovered Data in NetBox Assurance
  • Accessing NetBox Assurance
  • Explore Deviation Types
  • View Active Deviations
  • Apply Deviations
• View the Panorama Data in NetBox
• Additional Resources
  • Related Documentation
  • Support

Prerequisites

Before you begin, ensure you have the following:

• NetBox Cloud or NetBox Enterprise with NetBox Assurance
• Orb Agent Pro credentials (required to download the integration agent image)
• Palo Alto Networks Panorama managing the firewalls you want to sync. Firewalls that Panorama does not manage are not read
• A read-only Panorama account with access to Panorama's XML API, as an API key or a username and password
• Host system with Docker support
• Network connectivity between your host and both your NetBox instance and Panorama. The host does not connect to the firewalls

Host Requirements

System

• Operating System: Linux, macOS, or Windows with Docker support
• Memory: Minimum 2 GB RAM (4 GB recommended)
• Storage: 1 GB free disk space
• Docker: Version 20.10 or later

Network

• Outbound gRPC/gRPCS access to Diode on your NetBox instance (typically port 443 for gRPCS)
• Outbound HTTPS access to Panorama's management interface, on port 443 or the port you set in PANORAMA_HOST
• DNS resolution for both NetBox and Panorama, if you use host names
• Firewall rules configured to allow the above connections from your agent host

If the agent host reaches Panorama through a proxy, set PANORAMA_PROXY in the agent configuration.

Panorama Setup

Choose Panorama credentials

The integration reads Panorama, and the firewalls through Panorama, with one Panorama account. It runs operational show commands only, so the account needs read-only access. Firewalls need no credentials of their own.

Choose one of two credential paths:

• API key - set PANORAMA_API_KEY to an API key for the account. The key is sent in the X-PAN-KEY header.
• Username and password - set PANORAMA_USERNAME and PANORAMA_PASSWORD. The integration generates an API key from them at the start of each run.

Set one path only. Setting both is an error, and the run sends nothing.

NetBox Setup

Generate Diode Client Credentials

1. Log in to your NetBox instance.
2. Navigate to Diode → Client Credentials.
3. Click + Add a Credential.
4. Enter a descriptive name (for example, "Panorama Integration").
5. Click Create.

6. Important: Copy and securely store the Client ID and Client Secret - you will need them in the agent configuration.

7. Navigate to Diode → Settings.
8. Copy the Diode target value - you will use this in the agent configuration file.

Agent Setup and Configuration

Step 1: Authenticate to the NetBox Labs Image Registry

From your host machine, authenticate to the NetBox Labs registry using the CUSTOMER-IDENTIFIER and token provided by the NetBox Labs team:

docker login quay.io -u netboxlabs+<CUSTOMER-ID> -p <TOKEN>

Example session:

% docker login quay.io -u netboxlabs+org-abc123def456 -p <token>
Login Succeeded

Then pull the agent image:

docker pull quay.io/netboxlabs/orb-agent-pro:develop

Step 2: Configure the Agent

1. Create the configuration file (you can name the file anything you like):

touch agent.yaml

2. Edit the configuration file and add the following. Replace grpcs://your-instance.netboxcloud.com/diode with the value from Diode → Settings → Diode target in the NetBox UI:

orb:
  config_manager:
    active: local
  backends:
    worker:
    common:
      diode:
        target: grpcs://your-instance.netboxcloud.com/diode # Get this value from Diode > Settings > Diode target
        client_id: ${DIODE_CLIENT_ID}
        client_secret: ${DIODE_CLIENT_SECRET}
        agent_name: panorama_01  # Use a meaningful name to identify this agent
  policies:
    worker:
      panorama_worker:
        config:
          package: nbl_paloalto_panorama
          schedule: "0 2 * * *" # Daily at 2:00 AM. Set your desired schedule (see examples below)
          PANORAMA_HOST: ${PANORAMA_HOST}        # A bare host, host:port, or an https:// URL
          PANORAMA_API_KEY: ${PANORAMA_API_KEY}  # Or set PANORAMA_USERNAME and PANORAMA_PASSWORD instead
          PANORAMA_NAME: panorama-prod           # Names the Panorama in the default site, a tag, and a custom field
          BOOTSTRAP: True  # Set to True for initial setup, False for regular operation
          # SITE_NAME: HQ                                     # Optional: put every firewall in one site
          # SITE_FROM_HOSTNAME_REGEX: "^(?P<site>[a-z]+)-fw"  # Optional: take the site from each hostname
          # PANORAMA_SYNC_LINK_STATE: true                    # Optional: set to false to stop sending the live link state (default: true)
          # PANORAMA_SSL_VERIFY: true                         # Optional: set to false only for a self-signed certificate (default: true)
          # PANORAMA_PROXY: https://proxy.example.com:3128    # Optional: proxy for requests to Panorama
          # PANORAMA_TIMEOUT_SECONDS: 60                      # Optional: timeout for each request, in seconds (default: 60)
        scope:
          # device_groups: ["branch"]          # Optional: sync only these device groups and their child groups
          # serials: ["007954000918414"]       # Optional: sync only these firewalls

To use a username and password instead of an API key, replace the PANORAMA_API_KEY line with:

          PANORAMA_USERNAME: ${PANORAMA_USERNAME}
          PANORAMA_PASSWORD: ${PANORAMA_PASSWORD}

Scope Configuration

The scope section limits which firewalls are synced. Configure it under a scope key in the policy, separate from config.

• device_groups - a list of device group names. A firewall is synced when its device group is one of these, or a child group of one of these at any depth.
• serials - a list of firewall serial numbers.

Example:

scope:
  device_groups: ["branch", "datacenter"]

When both keys are set, a firewall must match both. Each key must be a list. Omit the scope section to sync every firewall that Panorama manages. See scope Parameters for details.

Bootstrap Mode (First-Time Setup)

Bootstrap mode creates the static content in NetBox that the integration requires before the first full sync. Run it once on initial setup, then disable it for all subsequent runs. In bootstrap mode the integration makes no Panorama API calls, so the host and credentials are not required.

What bootstrap mode creates:

• Tags: paloalto, panorama, discovered, and panorama-<name> when PANORAMA_NAME is set
• Custom fields: nbl_matching_id, panorama_instance, panorama_connected, panorama_device_group, panorama_template_stack, panorama_templates, panorama_routing_engine, panorama_ha_state, panorama_ha_peer_serial, panorama_ha_mode, panorama_link_state, panorama_zone, panorama_vrfs
• The Palo Alto Networks manufacturer
• The Firewall device role

Configuration:

config:
  BOOTSTRAP: true  # Set to true for initial setup, false for regular operation

First-time run process:

1. Set BOOTSTRAP: true in your configuration.
2. Run the agent and monitor the output for executed successfully.
3. Stop the agent by pressing Ctrl+C once you see executed successfully.
4. Apply the deviations in NetBox Assurance (see Apply Deviations below).
5. Set BOOTSTRAP: false for all future runs.

Optional - Dry Run Mode

The agent can run in dry run mode, which writes discovered data to a JSON file instead of sending it to NetBox. This is useful for checking what the integration will create before the first real sync, or for sharing data with the NetBox Labs support team.

Add the following to the diode section of your configuration:

      diode:
        dry_run: true
        dry_run_output_dir: /opt/orb/  # Output file is written to this directory

Step 3: Run the Agent

Run the agent to synchronize the firewalls into NetBox. The current directory, containing agent.yaml, is mounted into the container at /opt/orb/.

Method 1: Set Environment Variables Manually

1. Export Diode credentials:

export DIODE_CLIENT_ID="your-client-id"
export DIODE_CLIENT_SECRET="your-client-secret"

2. Export Panorama connection details:

export PANORAMA_HOST="panorama.example.com"
export PANORAMA_API_KEY="your-panorama-api-key"

3. Run the agent:

docker run \
  -v $PWD:/opt/orb/ \
  -e DIODE_CLIENT_SECRET \
  -e DIODE_CLIENT_ID \
  -e PANORAMA_HOST \
  -e PANORAMA_API_KEY \
  quay.io/netboxlabs/orb-agent-pro:develop \
  run -c /opt/orb/agent.yaml

Method 2: Use a .env File (Recommended)

1. Create a .env file:

touch .env

2. Edit the .env file and add the following:

## NetBox Diode credentials (from NetBox Setup)
DIODE_CLIENT_ID=your-client-id
DIODE_CLIENT_SECRET=your-client-secret

## Panorama connection
PANORAMA_HOST=panorama.example.com
PANORAMA_API_KEY=your-panorama-api-key

3. Run the agent:

docker run \
  -v $PWD:/opt/orb/ \
  --env-file .env \
  quay.io/netboxlabs/orb-agent-pro:develop \
  run -c /opt/orb/agent.yaml

echo ".env" >> .gitignore

Expected Output

After starting the agent, you will see log output as the integration reads Panorama and sends data to NetBox. This example is from a Panorama managing two firewalls:

{"time":"2026-10-22T02:00:01.123456789Z","level":"INFO","msg":"worker stderr","log":"INFO:nbl_paloalto_panorama.builders.tags:Built 4 tags"}
{"time":"2026-10-22T02:00:01.234567890Z","level":"INFO","msg":"worker stderr","log":"INFO:nbl_paloalto_panorama.builders.custom_fields:Built 13 custom-field definitions"}
{"time":"2026-10-22T02:00:01.901234567Z","level":"INFO","msg":"worker stderr","log":"INFO:nbl_paloalto_panorama.builders.devices:Built 2 devices"}
{"time":"2026-10-22T02:00:02.345678901Z","level":"INFO","msg":"worker stderr","log":"INFO:nbl_paloalto_panorama.builders.management:Built 2 management interfaces"}
{"time":"2026-10-22T02:00:02.456789012Z","level":"INFO","msg":"worker stderr","log":"INFO:nbl_paloalto_panorama.builders.virtual_device_contexts:Built 0 virtual device contexts"}
{"time":"2026-10-22T02:00:02.567890123Z","level":"INFO","msg":"worker stderr","log":"INFO:nbl_paloalto_panorama.builders.interfaces:Built 0 dataplane interfaces"}
{"time":"2026-10-22T02:00:02.678901234Z","level":"INFO","msg":"worker stderr","log":"INFO:nbl_paloalto_panorama.builders.ip_addresses:Built 0 dataplane IP addresses"}
{"time":"2026-10-22T02:00:02.789012345Z","level":"INFO","msg":"worker stderr","log":"INFO:nbl_paloalto_panorama.builders.mac_addresses:Built 2 MAC addresses"}
{"time":"2026-10-22T02:00:02.890123456Z","level":"INFO","msg":"worker stderr","log":"INFO:nbl_paloalto_panorama.panorama_diode:Returning 32 entities"}
{"time":"2026-10-22T02:00:03.901234567Z","level":"INFO","msg":"worker stderr","log":"INFO:worker.policy.runner:Policy panorama_worker: Successful ingestion"}
{"time":"2026-10-22T02:00:04.012345678Z","level":"INFO","msg":"worker stderr","log":"INFO:apscheduler.executors.default:Job \"PolicyRunner.run\" executed successfully"}

With a username and password, the output also includes Generated a Panorama API key from the username and the password.

View and Apply Discovered Data in NetBox Assurance

After the agent runs, work with the discovered Panorama data in NetBox Assurance.

NetBox Assurance identifies deviations between data already in NetBox and the actual operational state discovered by the integration.

Accessing NetBox Assurance

1. Navigate to your NetBox instance UI.
2. Click on Assurance in the main navigation menu.

Explore Deviation Types

1. Click on Deviation Types to view the categories of deviations discovered.

2. Click the Name of a deviation type to view deviations of that type.

3. Click the Name of an individual deviation to view its details.

View Active Deviations

1. Click on Active Deviations to view all deviations that have not yet been applied or ignored.

2. Click the Name of a deviation to view its details.

Apply Deviations

1. Select the deviations you want to apply. For large result sets, set Per Page to 500 first.

2. Select the first deviation, hold SHIFT, select the last one, then click Apply Selected.

3. Click Apply X Deviations to write the data to NetBox.

View the Panorama Data in NetBox

After running the integration and applying discovered data, you can navigate the firewalls in NetBox:

1. Navigate to Devices and filter by the Firewall role to see each firewall with its model, platform, serial number, and the panorama_* custom fields.
2. Open a firewall's interfaces to see the management interface and the dataplane interfaces, with their addresses, VRFs, and the panorama_zone and panorama_link_state custom fields.
3. Navigate to IPAM → VRFs to see each firewall's routing instances, named <hostname>:<instance>, and its <hostname>:management VRF.
4. Navigate to IPAM → VLAN Groups to see each firewall's VLANs, in a group named firewall-serial: <serial>.
5. On a multi-vsys firewall, open Virtual Device Contexts to see its virtual systems.

Additional Resources

Related Documentation

• NetBox Assurance Documentation
• Orb Agent Documentation
• Palo Alto Panorama Integration - Technical Information

Support

Email support@netboxlabs.com for support.