Technical Information

Panorama to NetBox Object Mapping

This page describes how Panorama and firewall data is mapped to NetBox objects by the integration.

Data flows in one direction only, from Panorama to NetBox. The integration never writes to Panorama or to a firewall.

The integration connects only to Panorama, over its XML API at https://<PANORAMA_HOST>/api/. Some calls read Panorama itself. The rest are relayed: Panorama sends the command to one managed firewall, identified by its serial number, and returns that firewall's answer. Every call is a read-only operational show command:

When the policy gives a username and a password instead of an API key, the integration first generates an API key with a key-generation request.

Relayed calls run one firewall after another, in serial-number order. A firewall that Panorama reports as disconnected gets no relayed call. See Firewalls that do not answer.

Object Type Mapping Table

Choosing a site and a Panorama name

Panorama does not record where a firewall stands, and the integration does not read the sites you already hold in NetBox. Decide where the firewalls land before the first run.

Site

Every firewall is placed in a site, chosen by these rules:

1. When SITE_FROM_HOSTNAME_REGEX is set and matches a firewall's hostname, the regex's named group site gives that firewall's site. For example, ^(?P<site>[a-z]+)-fw places lon-fw01 in the site lon.
2. Otherwise, when SITE_NAME is set, the firewall goes in that site.
3. Otherwise, the firewall goes in a site named after the Panorama instance: PANORAMA_NAME, or the hostname that Panorama reports when PANORAMA_NAME is not set.

A site is created only when a firewall lands in it.

NetBox identifies a device by its name and site before it checks the serial number, so the site is part of each firewall's identity:

• Changing the site rule after the first run moves every firewall it affects to the new site. The old site stays in NetBox, empty.
• Rename a site through the policy, never in NetBox. The integration sends the site by name on every run, so a site renamed in NetBox is created again under its old name, and the firewalls move back into it.
• If NetBox already holds your firewalls in their own sites, set SITE_NAME or SITE_FROM_HOSTNAME_REGEX before the first run. Otherwise the firewalls move into a new site named after Panorama.

Panorama name

The Panorama instance name is used in three places: the default site, the panorama-<name> tag, and the panorama_instance custom field. Set PANORAMA_NAME before the first run. Without it, the name is the hostname that Panorama reports, so renaming Panorama, or pointing the policy at the other Panorama of a high-availability pair, changes the name and moves every firewall in the default site to a new site.

Devices

Each firewall in Panorama's inventory, within the policy's scope, becomes one NetBox device.

Device fields

The status does not change when a firewall disconnects from Panorama. The connection is recorded in the panorama_connected custom field instead.

Device custom fields

A field is sent only when it has a value. For example, a firewall that is not in a high-availability pair gets none of the three panorama_ha_* fields, and a firewall that two device groups list gets no panorama_device_group (the integration logs a warning naming both groups). The same applies to a firewall that two template stacks list: it gets no panorama_template_stack or panorama_templates.

Because an empty value is never sent, a field whose value goes away keeps its last value in NetBox. For example, when a firewall leaves its device group, panorama_device_group keeps the old group until the firewall joins another one.

Device identity

Each firewall records its serial number in nbl_matching_id. NetBox matches a device by its management address, then by its name and site, and then by this matching ID:

• A firewall that two Panoramas report becomes one device, for example during a migration. Both policies must place it in the same site, by setting the same SITE_NAME or SITE_FROM_HOSTNAME_REGEX, or it moves between two sites on every run. While both Panoramas report it, panorama_instance, panorama_connected, panorama_device_group, panorama_template_stack, and panorama_templates change on every run, each producing a deviation.
• A firewall you rename in NetBox is found again on the next run by its serial number. It is not created a second time under its old name.
• Two firewalls that report the same hostname into one site become one device. NetBox matches them by name and site before it checks the serial number, so the merged record alternates between the two on every run. This is common for firewalls left at a factory hostname such as PA-VM. The integration does not change the names. It logs a warning naming the hostname, the site, and every serial number. Rename all but one of the firewalls in Panorama, and the next run separates them.

A firewall that reports no usable serial number (none, or unknown) is still recorded, from the inventory, but gets no nbl_matching_id, no panorama_device_group, panorama_template_stack, or panorama_templates, no VLAN group, no routing instance, no relayed call, and no addresses. The integration logs a warning for it. A managed device that reports neither a hostname nor a usable serial number is skipped, with a warning.

Firewalls that do not answer

A firewall that Panorama reports as disconnected is recorded from the inventory alone: its name, serial number, device type, platform, role, site, status, and the custom fields the inventory supplies. It gets no management interface, no management addresses or primary IP, no dataplane interfaces, and no panorama_routing_engine. A multi-vsys firewall keeps its virtual device contexts, because they come from the inventory.

When a relayed call fails on one firewall, the integration logs a warning naming the call, the firewall, its serial number, and what the run does without the answer, and continues with the other firewalls:

When a relayed call fails with an HTTP error, a timeout, or a connection error, the integration then asks Panorama for its own show system info. If Panorama does not answer either, the run fails.

A failed call to Panorama itself, such as show devices all, show devicegroups, or show template-stack, fails the run. An error answer is logged as Panorama answered with PAN-OS code <code>: <message>, and an HTTP status other than 200 or 403 as Panorama answered HTTP <status> <reason>.

Management Interface

PAN-OS does not list the management port with the dataplane interfaces, so the integration builds it from each firewall's relayed show system info:

• Interface - named management, marked management only and enabled. Its type is virtual on a VM-Series firewall and other on any other model.
• VRF - <hostname>:management, a routing instance of its own, because PAN-OS routes the management port apart from every virtual router. Two firewalls behind NAT that report the same management address therefore stay separate.
• IPv4 address - the management address from Panorama's inventory, with the netmask the firewall reports. If the firewall reports no netmask, the address is skipped with a warning, and the device gets no primary IPv4 address.
• IPv6 address - the management IPv6 address the firewall reports, when it has one.
• Status - dhcp when the firewall reports that the address came from DHCP, otherwise active.
• Primary IP - the management IPv4 and IPv6 addresses become the device's primary IPv4 and IPv6 addresses.
• MAC address - the management MAC address, when it is unique (see MAC Addresses).

Only a firewall that answers both show system info and show interface all gets a management interface.

Dataplane Interfaces

Each interface that a firewall's show interface all reports becomes one NetBox interface on that firewall. An interface that only the configuration names, and the firewall does not report, is not created.

Interface type and parent

A physical port's type is generic because neither Panorama nor the firewall reports what a port physically is. Its negotiated speed is recorded separately.

Interface fields

What the firewall reports decides every field it can answer. The running configuration supplies a value only where the listing is silent. An interface the running configuration does not name is enabled and has none of the configuration fields. A firewall whose running configuration could not be read gets none of them on any interface.

Enabled records whether an operator turned the interface on, not whether its link is up. A port held down by high availability is still shown as enabled. Its live link state is in panorama_link_state.

Link state

panorama_link_state records whether each interface's link is up now. It changes whenever a cable is pulled or a high-availability pair fails over, and each change is a deviation to review.

To stop sending it, set PANORAMA_SYNC_LINK_STATE: false. The field then holds the value not synced on every interface that reports a link state. The first run after the change updates every such interface once, so expect one deviation per interface. After that the field does not change. Set the key back to true, and the next run restores the real values, again with one deviation per interface.

Routing Instances

Each firewall's routing instances become NetBox VRFs of their own. The VRFs are per firewall, not shared, because the two members of a high-availability pair hold identical interface addresses, and the VRF keeps them apart.

The hostname is the firewall's NetBox device name. An interface with no routing instance and no address gets no VRF.

Route distinguishers

Each VRF's route distinguisher is pan: followed by 16 hexadecimal characters, derived from a hash of the firewall's serial number and the instance name, for example pan:be6889a440ca4720 for the instance default on the firewall 007954000918414. The management and unassigned VRFs are derived from the serial number alone. It identifies the NetBox VRF, so a VRF keeps its identity when the firewall is renamed, and two firewalls with the same hostname keep separate VRFs. It is not a route distinguisher used in your network, and must not be copied into a routing configuration.

Routing engine

A firewall runs either the classic routing engine, with virtual routers, or Advanced Routing, with logical routers. The integration reads which one from the firewall's show system info, records it in panorama_routing_engine, and reads each interface's routing instance accordingly: vr:<name> on the classic engine and logical-router:<name> on Advanced Routing.

When an interface's routing instance does not match the firewall's engine, the interface is recorded without a VRF and without addresses for that run, and the integration logs a warning naming the firewall, the interface, and the value. A firewall that does not report its routing engine accepts neither form, so each of its interfaces that names a routing instance is recorded without a VRF and without addresses, and the warning names the engine as unknown.

Advanced Routing has not been tested against a live firewall. See Known Limitations.

IP Addresses

Each address that an interface reports becomes a NetBox IP address:

• Address - the address with its prefix length, as the firewall reports it.
• VRF - the interface's VRF.
• Assigned to - the interface.
• Status - dhcp when the running configuration runs the DHCP client on the interface for the address's family, otherwise active. When the firewall's running configuration could not be read, no status is sent.

Link-local addresses are skipped. A value without a prefix length, or one that is not an address, is skipped with a warning.

When two interfaces of one firewall report the same address in the same VRF, the address is recorded once, on the interface whose name sorts first, and the integration logs a warning naming the other interfaces. NetBox finds an IP address by its value within its VRF, regardless of prefix length, so recording it on both would move one record between the two interfaces on every run.

An interface that gets its address from DHCP contributes that address with the status dhcp. When the lease moves, the new address is created as a new record, and the old record stays in NetBox. Filter IP addresses by the DHCP status to find them.

VLANs

Each subinterface that carries an 802.1Q tag from 1 to 4094 is set to tagged mode, with that one VLAN in its tagged VLANs. A tag of 0 means no VLAN. The units of the vlan interface (vlan.N) do not carry a VLAN ID, so they get none.

• VLAN - named VLAN <vid>, status active, with no site.
• VLAN group - one per firewall, named firewall-serial: <serial>, with the firewall's hostname as its description and its serial number in nbl_matching_id. The group is not scoped to a site.

A firewall with no tagged interface gets no VLAN group. VLANs on different firewalls are separate NetBox VLANs, even when they share a VLAN ID.

MAC Addresses

Each MAC address that exactly one interface reports, across all the firewalls in the run, becomes a NetBox MAC address assigned to that interface, and the interface's primary MAC address. MAC addresses are recorded in upper case with colons.

A MAC address that more than one interface reports is dropped from all of them, and the integration logs a warning naming each firewall and interface. A shared MAC address would let one firewall's interface match another's. VM-Series firewalls commonly report the same MAC addresses as each other, so they contribute few MAC addresses.

Virtual Systems

Each virtual system of a multi-vsys firewall becomes a NetBox virtual device context on that firewall:

• Name - the virtual system's display name, or its entry name, such as vsys2, when it has none.
• Identifier - the virtual system's number, for example 2 for vsys2.
• Status - active.
• panorama_vrfs - the VRFs that the virtual system's own interfaces use.

Each interface on a multi-vsys firewall references the virtual device context of its virtual system. A firewall with a single virtual system gets no virtual device context.

Custom Fields

The integration creates the following custom fields. All are created during bootstrap, and all are read-only in the NetBox UI.

The nbl_matching_id definition is shared with other NetBox Labs integrations and covers further object types, such as sites and virtual machines. This integration sets it only on devices and VLAN groups.

Tags

Every object the integration creates, except custom fields, is tagged:

• paloalto, panorama, and discovered
• panorama-<name>, where <name> is the Panorama instance name (see Panorama name), for example panorama-panorama-prod

The tags are also applied to shared objects such as the Palo Alto Networks manufacturer, the Firewall role, platforms, device types, and the sites the firewalls land in. If SITE_NAME names an existing site, that site receives the tags.

Device groups, templates, zones, and other values an operator can change are recorded in custom fields, not tags.

Configuration Parameters

Configure these under the config key in the policy definition.

* Not required in bootstrap mode.

** Set exactly one credential path: PANORAMA_API_KEY, or PANORAMA_USERNAME with PANORAMA_PASSWORD. Not required in bootstrap mode.

A missing PANORAMA_HOST, or a credential path that is missing or set twice, logs an error, and the run sends nothing. A value that is set but malformed, such as an http:// host or a SITE_FROM_HOSTNAME_REGEX without a site group, fails the run with an error naming the key.

scope Parameters

The scope key in the policy definition is optional and limits which firewalls are synced. Omit it to sync every firewall that Panorama manages.

scope:
  device_groups: ["branch"]
  serials: ["007954000918414"]

• When both keys are set, a firewall must match both.
• Each key must be a list. A value that is not a list fails the run, so a mistyped filter never syncs the whole estate. An empty list, or a list containing *, does not filter.
• A device group that Panorama does not report logs a warning naming it.
• A scope that matches no firewall logs a warning, and the run records no firewall.
• Each run with a scope logs how many firewalls it matched, as Scope: <n> of <total> managed devices.
• Narrowing the scope does not remove anything. Firewalls synced under a wider scope stay in NetBox.

Authentication and Connection

The integration authenticates to Panorama with one of two credential paths:

• API key - set PANORAMA_API_KEY. The key is sent in the X-PAN-KEY header on every request, never in the URL.
• Username and password - set PANORAMA_USERNAME and PANORAMA_PASSWORD. At the start of each run, the integration exchanges them for an API key with a key-generation request, sent as a form POST so that the password is not in the URL, and logs Generated a Panorama API key from the username and the password.

The account needs read-only access, including access to Panorama's XML API, to run operational commands on Panorama and to have them relayed to the managed firewalls. Firewalls need no credentials of their own.

If Panorama refuses the credentials with HTTP 403, on any call, the run fails.

TLS verification

TLS verification is enabled by default. Set PANORAMA_SSL_VERIFY: false to skip it, for example for a lab Panorama with a self-signed certificate.

Requests

• Timeout - each request times out after PANORAMA_TIMEOUT_SECONDS, 60 seconds by default.
• Retries - GET requests that fail with a connection error, a timeout, or HTTP status 429, 502, 503, or 504 are retried up to three times with backoff, so one request can take up to four times PANORAMA_TIMEOUT_SECONDS, plus the backoff. The key-generation request is not retried.
• Redirects - redirects are not followed, so the API key and the password are never sent to another host. A redirect fails the request.
• Proxy - set PANORAMA_PROXY to send requests to Panorama through a proxy.

Bootstrap Mode

When BOOTSTRAP is set to True, the integration creates the following without connecting to Panorama:

• 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

PANORAMA_HOST and the credentials are not required. If PANORAMA_HOST is set, it must still be a valid value. Use bootstrap mode on the initial setup only, then set it to False for all subsequent runs.

Sync Behavior

• Direction: One-way, Panorama to NetBox. The integration does not write to Panorama or to the firewalls.
• Object deletion: The integration does not delete NetBox objects. Firewalls removed from Panorama, interfaces and addresses removed from a firewall, and sites left empty by a change of site rule all remain in NetBox. Handle these removals manually.
• Idempotency: Subsequent runs update existing NetBox objects rather than creating duplicates. The Diode SDK handles conflict resolution.
• Unchanged values: Values that change between two runs against an unchanged estate, such as uptime, content versions, and configuration checksums, are not read, so they produce no deviations.
• Multiple Panoramas: Each policy reads one Panorama. Run a separate policy for each Panorama, each with its own PANORAMA_NAME.

Known Limitations

• Security policy is not synced. Security rules, NAT rules, address objects, and other policy configuration are not read. Each interface's security zone is recorded in panorama_zone.
• Advanced Routing has not been tested. The integration was tested only on firewalls that use the classic routing engine. On a firewall that uses Advanced Routing, it expects each interface's routing instance as logical-router:<name>. If the firewall reports its routing instances in another form, its interfaces are recorded without VRFs and without addresses, and the integration logs a warning naming the firewall, the interface, and the value. See Routing engine.
• Only firewalls that Panorama manages are synced. A firewall that Panorama does not manage is not read.
• Two firewalls with one hostname in one site become one device. NetBox matches them by name and site before the serial number, so the record alternates between them on every run. Rename all but one in Panorama. See Device identity.
• High-availability pairs are recorded in custom fields, not modeled. Each member records its state, its peer's serial number, and the pair's mode. No NetBox redundancy group is created.
• Floating addresses of an active/active pair are not marked. Such an address appears in the VRF of the firewall that reported it. After a failover it can appear under both firewalls, and the older record stays. Use panorama_ha_mode to tell this from a duplicate.
• A MAC address that more than one interface reports is not recorded. VM-Series firewalls therefore contribute few MAC addresses.
• Physical ports have a generic type. Ports are other, or virtual on a VM-Series firewall, because the port's medium is not reported.
• A port held down by high availability is shown as enabled. Enabled is the configured state. The live link state is in panorama_link_state.
• Link state changes produce deviations. Each link change or failover changes panorama_link_state. Set PANORAMA_SYNC_LINK_STATE: false to stop sending it.
• Old DHCP addresses stay in NetBox. When an interface's DHCP lease moves, the old address record remains, with the status dhcp.
• Custom field values are not cleared. A custom field whose value goes away, such as a device group the firewall has left, keeps its last value in NetBox.
• Route distinguishers are generated. Each VRF's pan: route distinguisher identifies the NetBox object and is not a value from your network.
• The site named in SITE_NAME receives the integration's tags. Bear this in mind if SITE_NAME names an existing site.
• Relayed calls run one firewall at a time. Each connected firewall costs several relayed calls, so a run against a large estate takes correspondingly longer.