Palo Alto

Clarity Transform reads security policy from a Palo Alto next-generation firewall over the PAN-OS XML API and uses it to infer which discovered devices are permitted to communicate. Read-only throughout; nothing is written to the appliance.

Where to find it

Go to Discover → Integrations, then select the Palo Alto card. The card's category label is Security. The integration's page has the Endpoints and History tabs; Integrations describes the page, its grid and its row actions.

Why we do this

Firewall policy is a complementary axis to observed traffic, and the pair is worth more than either alone. Firewall policy describes every conversation that is permitted to happen.

What we collect

Security rules, together with the address objects, address groups and service objects they reference. Clarity then resolves each rule's source and destination back to devices and networks already in the inventory.

• Security rules per vsys, with source, destination, service, application and action
• Address objects and groups
• Service objects
• Inferred device-to-device relationships where both ends resolve

What it adds

App-ID applications used in a rule are resolved to their default ports by asking the appliance itself, rather than from a bundled lookup table that would drift from the installed content version.

Device and manager are not the same thing, and where both exist we read both

Reading only the device would miss centrally authored intent; reading only the manager would miss anything configured locally.

What is deliberately not inferred

• No traffic content, packet captures or firewall logs. Configuration only.
• Nothing is written back to the appliance at any point, and the account used has no permission to do so.
• A rule is not a dependency. A rule is promoted to a CMDB relationship only where both its source and destination resolve to a device or network already discovered, and where it is specific enough to describe a dependency rather than a broad policy. An any-to-any rule is a statement about posture, so it is read and discarded.

Rule order is not evaluated

Firewall evidence means "a rule names this pair and port", not "this traffic would pass". A rule shadowed by a preceding deny still produces evidence. Deny, disabled, negated-address, negated-service and port-less rules are refused before they reach inference, so shadowing is the one case that is not detected. Treat a permitted-only finding as a lead to verify rather than a conclusion.

What we require

The requirement below is read from rb-pautol-panos-connect.ps1 in the Runbooks repository, which is where it is maintained. If it is wrong, the runbook is what gets corrected and this page follows on the next build.

Role required: superuser_read_only (PAN-OS's own read-everything-change-nothing role). Discovery reads configuration only; it never writes to the device.

Connectivity: the PAN-OS XML API over HTTPS on TCP 443 from Clarity to the firewall's management interface.

PAN-OS calls every named login - full-privilege or not - an "Administrator". That word describes where the account is configured (Device > Administrators), not what it can do. A superuser_read_only administrator cannot change a single setting on the device: do not let "Administrator" read as "privileged" in anything derived from this file.

Verification before handover

1. Confirm the key exchange works. POST to /api/ with type=keygen and the account credential. A response containing a key means authentication is working.
2. Confirm the rulebase is readable. Request the security rules for the vsys in scope. success with a populated result confirms the role is sufficient. success with an empty result is the answer to watch for, and usually means the endpoint is a Panorama rather than a firewall.
3. Confirm the account cannot write. Attempt any configuration set as this account and confirm it is refused. Worth doing once so the read-only claim is demonstrated rather than asserted.

Configuring the endpoint

On the integration's Endpoints tab, select the add icon (Create New Integration Endpoints). The Create new entry form opens with these fields, in this order:

Field	Value
Name	A name for the endpoint
End Point	The firewall's management hostname or IP
Credential	The stored credential for the read-only administrator
Job Schedule	A five-field cron expression. Policy changes slowly. Daily (0 2 * * *) is ample; weekly (0 2 * * 0) is defensible on a stable estate
Enabled	Ticked. The box is unticked when the form opens

The help texts: End Point "FQDN or IP Address of management system for technology e.g. vCenter, Nutanix Prism"; Credential "Credentials can be configured under Settings/Identity and Access Management/Credentials."; Job Schedule "Cron schedule – Use five fields: 〈mm〉 〈hh〉 〈day-of-month〉 〈month〉 〈weekday〉".

The Credential list offers the credentials stored under Settings → Identity & Access Management → Credentials, so create the credential there first.

No field is marked as required. Technology is set by the card and is hidden in the form. Select Save to create the endpoint, or Cancel to close the form. The edit icon opens the same fields as Edit entry.

Removing the access

Delete the account on the appliance. Nothing else is left behind: Clarity creates no objects and holds no session once a run ends. Then, in Clarity, remove the endpoint (select its row on the Endpoints tab, then Remove selected) or clear its Enabled box, and remove the credential under Settings → Identity & Access Management → Credentials.

Troubleshooting

Symptom	Cause
Authentication fails at the key exchange	Wrong credential, or the account is locked. The role is not involved.
success with an empty result and no rules	The endpoint is a Panorama, not a firewall. Use the Panorama integration.
Rules read but no relationships created	Expected where rule endpoints do not resolve to discovered devices. Run the hypervisor and operating system integrations first, then re-run.
A read returns a permission error	The role is not read-only superuser, or a custom role is in use that omits the branch being read.