Skip to main content

Configuration details

This documentation represents the current state of the available checks and snapshot state areas, along with the instructions on how to configure them properly.

Passing configuration in general​

For most use cases, all checks, snapshots and reports (entities in general) are triggered by a common method, which:

  • takes a list of checks, snapshots, reports (entities) that one would like to run,
  • does initial list verification,
  • picks up a proper method to run a specific entity,
  • aggregates and presents the results in a form of a dictionary, where keys represent requested entities.

The list of entities can be just a list, but it can also follow the ConfigParser dialect. For more details, refer to the dialect's documentation. The most important is that this dialect supports two types of elements in the list: str and dict, where:

  • str represents just an entity name such as a check, snapshot or report to run,
  • dict (always single key:value pair allowed) represents the element name (key) and additional configuration (value) that will be passed to the method matching the particular element. This configuration is also passed as dict.

In the next sections of this documentation, the following aspects are covered:

  • a common method with full configuration (where applicable),
  • each entity available in a particular section with some basic information and a link to a method that is actually run. For details, see documentation for methods.
note

Each entity is documented under its own section where the section name is the entity name.

Readiness checks​

Readiness checks represent checks that are boolean in nature. A result of such checks always presents a True/False value with some explanation in case of check fails. They can be triggered with a common method: CheckFirewall.run_readiness_checks(). When running this method, a list of readiness checks to run (with an optional configuration) is provided using the checks_configuration parameter. This list is defined using the ConfigParser class dialect. For details, refer to the documentation for this class.

Elements of this list can be either of the str or dict type:

  • str - the element simply specifies the name of a check to run.

  • dict - the element contains the check name and a configuration (if a particular check requires one); the dictionary format is as follows:

    {
      'check_name': {
        'config_name': 'config_value',
        'config2_name': 'config2_value'
      }
    }

Following ConfigParser's dialect, when no configuration is provided, all checks are triggered. Notice that in this situation checks that require configuration to run will return CheckStatus.SKIPPED.

Example of the checks_configuration parameter:

checks_configuration = [
    'all',
    '!ha',
    {'content_version': {
        'version': '8634-7678'
    }}
]

This is interpreted as:

  • run all checks
  • except for the HA status verification
  • override the Content DB version check to check for the minimum version of 8634-7678.

The CheckFirewall.run_readiness_checks() take one more parameter: report_style. Format of the returned data depends on the value of this parameter. If the value is:

  • False (default): results of executed checks are formatted as dict, where keys are check names as passed in checks_configuration and values are dictionaries containing two keys:

    • state: a bool representation of the CheckResult class for a particular check.

    • reason: a str representation of the CheckResult class for a particular check.

      Assuming that we run the checks with the following configuration:

      checks_configuration = [
          'ha',
          'panorama',
      ]

      The return dict should look as follows:

      result = {
          'ha': {
              'state': False
              'reason': '[FAIL] Device configuration is not synchronized between the nodes.'
          }
          'candidate_config': {
              'state': True
              'reason': '[SUCCESS]'
          }
      }

  • True: results are also formatted as dict with the keys corresponding to checks names, but values are a string representations of the CheckResult class.

    For the above example of checks, the result would be similar to:

    result = {
        'ha': '[FAIL] Device configuration is not synchronized between the nodes.'
        'candidate_config': '[SUCCESS].'
    }
    {
        'ha': '[FAIL] Device configuration is not synchronized between the nodes.'
        'candidate_config': '[SUCCESS].'
    }

The list of checks to run looks as follows:

checks_configuration = [
    "active_support",
    'candidate_config',
    'expired_licenses',
    'jobs',
    'ntp_sync',
    'panorama',
    # tests below have optional configuration
    {
        "certificates_requirements": {
            "ecdsa": {"hash_method": "sha512"},
            "rsa": {
                "key_size": 1024,
                "hash_method": "sha1"
            }
        }
    },
    {'content_version': {'version': '8634-7678'}},
    {'dynamic_updates': {'test_window': 120}},
    {"expired_licenses": {"skip_licenses": ["Threat Prevention"]}},
    {'free_disk_space': {'image_version': '10.1.6-h6'}},
    {'ha': {'skip_config_sync': True}},
    {'planes_clock_sync': {'diff_threshold': 30}}
    # tests below require additional configuration
    {'arp_entry_exist': {'ip': '10.0.1.1'} },
    {'ip_sec_tunnel_status': {
        'tunnel_name': 'ipsec_tun'
    }},
    {'session_exist': {
        'source': '134.238.135.137',
        'destination': '10.1.0.4',
        'dest_port': '80'
    }},
]

Please see the sections below for details of each check:

arp_entry_exist​

Checks if a specified ARP entry exists.

Method: CheckFirewall.check_arp_entry()

Configuration parameters

parameterdescription
ipIP address we look for
interface(optional) network interface name we would like to limit the search to

Sample configuration

Lookup limited to a single interface
checks_configuration = [
    {
        'arp_entry_exist': {
            'ip': '10.0.1.1'
            'interface': 'ethernet1/1'
        }
    }
]
Lookup in all ARP entries
checks_configuration = [
    {
        'arp_entry_exist': {
            'ip': '10.0.0.6'
        }
    }
]

candidate_config​

Verifies if there are any changes on the device pending to be committed. This can be either a loaded named config which requires a full commit or just some small changes made manually or with an CLI/API.

Does not require configuration.

Method: CheckFirewall.check_pending_changes()

certificates_requirements​

Verifies each certificates' properties against minimum requirements (keys size and hashing method). When run w/o any additional parameters the minimum requirements follow limitations introduced in PanOS 10.2.

Method: CheckFirewall.check_ssl_cert_requirements()

Configuration parameters

parameterdescription
rsa(optional) dictionary describing minimum requirements for RSA certificates
ecdsa(optional) dictionary describing minimum requirements for ECDSA certificates

Both dictionaries accept the following keys:

keydescription
hash_methoda minimum (from security perspective) required hashing method
key_sizea minimum size of a key.

Sample configuration

checks_configuration = [
    {
        "certificates_requirements": {
            "ecdsa": {
                "hash_method": "sha512"
            },
            "rsa": {
                "key_size": 1024,
                "hash_method": "sha1"
            }
        }
    }
]

content_version​

Compares currently installed Content DB version against either:

  • the latest available version if no config is passed,
  • specified versions if one config is passed.

Method: CheckFirewall.check_content_version()

Configuration parameters

paramterdescription
version(optional) a minimum Content DB version that would satisfy the check

Sample configuration

checks_configuration = [
    {
        'content_version': {
          'version': '6453-5673'
        }
    }
]

dynamic_updates​

Check if any Dynamic Update job is scheduled to run within the specified time window.

note

This includes schedules pushed from Panorama via a template, but does not include the ones configured in Panorama/Device Deployment/Dynamic Updates/Schedules.

Method: CheckFirewall.check_scheduled_updates()

Configuration parameters

paramterdescription
test_window(optional) time window in minutes to look for an update job occurrence

Sample configuration

checks_configuration = [
    {
        'dynamic_updates': {
          'test_window': 120
        }
    }
]

free_disk_space​

Checks if there is enough free space on the /opt/panrepo volume to download a PanOS image before an upgrade.

Method: CheckFirewall.check_free_disk_space()

Configuration parameters

paramterdescription
image_version(optional) target PanOS version to calculate required free space, when skipped arbitrary 3GB is used

Sample configuration

checks_configuration = [
    {
        'free_disk_space': {
            'image_version': '10.1.6-h3'
        }
    }
]

expired_licenses​

Checks and reports expired licenses.

Method: CheckFirewall.check_expired_licenses()

Configuration parameters

paramterdescription
skip_licenses(optional) a list of license names that should be excluded from verification

Sample configuration

checks_configuration = [
    { 'expired_licenses': {
        'skip_licenses': ['WildFire License', 'Threat Prevention']
        } 
    }
]

ha​

Verifies if an HA pair is in a correct state. Only Active-Passive configuration is supported at the moment.

Method: CheckFirewall.check_ha_status()

Configuration parameters

paramterdescription
skip_config_syncFlag to skip (True) configuration sync state between HA pair nodes.

Sample configuration

checks_configuration = [
    {
        'ha' : {
            'skip_config_sync': True
        }
    }
]

ip_sec_tunnel_status​

Verifies if a given IPSec tunnel is in active state.

Method: CheckFirewall.check_ipsec_tunnel_status()

Configuration parameters

paramterdescription
tunnel_nameA name of an IPSec tunnel which status we would like to verify

Sample configuration

checks_configuration = [
    {
        'ip_sec_tunnel_status': {
            'tunnel_name': 'ipsec_tunnel'
        }
    }
]

jobs​

Verify if there are any running/pending jobs in the job queue. Any job with a status different than FIN will cause the check to fail.

Does not require configuration.

Method: CheckFirewall.check_non_finished_jobs()

ntp_sync​

Verify if time on a device is synchronized with an NTP server. This check fails if no NTP synchronization is configured.

Does not require configuration.

Method: CheckFirewall.check_ntp_synchronization()

panorama​

Check if a device is connected to the Panorama server. This check fails if no Panorama configuration is present on a device.

Does not require configuration.

Method: CheckFirewall.check_panorama_connectivity()

planes_clock_sync​

Checks difference between clocks for Management and Data planes.

Method: CheckFirewall.check_mp_dp_sync()

Configuration parameters

paramterdescription
diff_threshold(optional) Maximum difference in seconds between clocks for management and data planes.

Sample configuration

checks_configuration = [
    { 
        'planes_clock_sync': {
            'diff_threshold': 25
        }
    }
]

session_exist​

Does a lookup in a sessions table for a named session. This check is appropriate for verifying if a critical session was established after a device upgrade/reboot.

Method: CheckFirewall.check_critical_session()

Configuration parameters

paramterdescription
sourceIP address from which the session was established
destinationIP address to which the session was established
dest_portTarget destination port

Sample configuration

checks_configuration = [
    {
        'session_exist': {
            'source': '134.238.135.137',
            'destination': '10.1.0.4',
            'dest_port': '80'
        }
    }
]

State snapshots​

State snapshots store information about the state of a particular device area. They do not take any configurations. They store every possible information about an area. Use reports or custom code to extract a subset of information if required.

They can be triggered using a common method: CheckFirewall.run_snapshots(). When running this method a list of state areas is provided using the snapshot_config paramter. This list is specified in ConfigParser class dialect. For details, refer to the documentation for this class.

Following that dialect, when no list is passed, all state snapshots are made.

The output of the CheckFirewall.run_snapshots() method is formatted as a dictionary where:

  • keys are state areas as passed in snapshot_config parameter,
  • values are dictionaries with the actual data. Each dictionary can have a different structure. The structure depends on the nature of data we want to capture (see sections below for details).

The sample output containing a snapshot for route tables, licenses, and IPSec tunnels is shown below (one element per each area):

{
  "ip_sec_tunnels": {
    "ipsec_tun": {
      "peerip": "10.26.129.5",
      "name": "ipsec_tun",
      "outer-if": "ethernet1/2",
      "gwid": "1",
      "localip": "0.0.0.0",
      "state": "init",
      "inner-if": "tunnel.1",
      "mon": "off",
      "owner": "1",
      "id": "1"
    },
  }.
  "routes": {
    "default_0.0.0.0/0_ethernet1/3": {
      "virtual-router": "default",
      "destination": "0.0.0.0/0",
      "nexthop": "10.26.129.129",
      "metric": "10",
      "flags": "A S",
      "age": null,
      "interface": "ethernet1/3",
      "route-table": "unicast"
    },
  },
  "license": {
    "DNS Security": {
      "feature": "DNS Security",
      "description": "Palo Alto Networks DNS Security License",
      "serial": "007257000334668",
      "issued": "November 08, 2022",
      "expires": "November 01, 2023",
      "expired": "no",
      "base-license-name": "PA-VM",
      "authcode": null
    },
  }
}

Following state areas are available:

snapshots_config = [
  'nics',
  'routes',
  'license',
  'arp_table',
  'content_version',
  'session_stats',
  'ip_sec_tunnels',
]

Please see the sections below for details of each state snapshot:

arp_table​

Makes a snapshot of ARP table.

Method: FirewallProxy.get_arp_table()

content_version​

Grabs the currently installed Content DB version.

Method: CheckFirewall.get_content_db_version()

ip_sec_tunnels​

Takes a snapshot of configuration of all IPSec tunnels along with their state.

Method: CheckFirewall.get_ip_sec_tunnels()

license​

Takes a snapshot of information about all licenses installed on a device.

Method: FirewallProxy.get_licenses()

nics​

Takes a snapshot of a state of all configured (not installed) network interfaces.

Method: FirewallProxy.get_nics()

routes​

Takes a snapshot of the Route Table (this includes routes populated from DHCP as well as manually entered ones).

Method: FirewallProxy.get_routes()

session_stats​

Gets information about the session statistics, such as current sessions count per a session type (TCP, UDP, etc).

Method: FirewallProxy.get_session_stats()

Reports​

The reporting part is actually the result of comparison of two snapshots. It is advised to run reports using the common method as some of the comparison results are calculated with it. The common method is: SnapshotCompare.compare_snapshots().

Each report can be run with default or custom configuration. The following example shows reports with additional configuration (where applicable):

reports = [
    {'ip_sec_tunnels': {
        'properties': ['state']
    }},
    {'arp_table': {
        'properties': ['!ttl'],
        'count_change_threshold': 10
    }},
    {'nics': {
        'count_change_threshold': 10
    }},
    {'license': {
        'properties': ['!serial']
    }},
    {'routes': {
        'properties': ['!flags'],
        'count_change_threshold': 10
    }},
    'content_version',
    {'session_stats': {
        'thresholds': [
            {'num-max': 10},
            {'num-tcp': 10},
        ]
    }}
]

For most reports, a generic comparison method is used (SnapshotCompare.get_diff_and_threshold()). It produces the standardized dictionary. For details, see documentation for this method. Common method assigns a report result to a report area providing a dictionary where keys are report areas and values are report results.

For details on which configuration can be passed, check each report area below (for each report, we will explain the above-mentioned configuration):

arp_table​

Runs comparison of ARP tables snapshots.

Method: SnapshotCompare.get_diff_and_threshold()

Configuration parameters

parameterdescription
properties(optional) a set of properties to skip when comparing two ARP table entries, all properties are checked when this parameter is skipped
count_change_threshold(optional) maximum difference percentage of changed entries in ARP table in both snapshots, skipped when this property is not specified

Sample configuration

The following configuration:

  • compares ARP table entries between both snapshots, but when comparing two entries the ttl parameter is not taken into consideration,
  • calculates the count of changed ARP table entries from both snapshots and marks comparison as failed if the difference is bigger than 10%.

This report produces the standardized dictionary.

reports = [
    {
        'arp_table': {
            'properties': ['!ttl'],
            'count_change_threshold': 10
        }
    }
]

content_version​

This is one of a few checks that does not take any configuration. It simply compares Content DB version from both snapshots. Results are presented as the standardized dictionary.

Method: SnapshotCompare.get_diff_and_threshold()

ip_sec_tunnels​

Compares configuration and the state of IPSec tunnels.

Method: SnapshotCompare.get_diff_and_threshold()

Configuration parameters

parameterdescription
properties(optional) a set of properties to skip when comparing two IPSec tunnels, all properties are checked when this parameter is skipped
count_change_threshold(optional) maximum difference percentage of changed entries in IPSec tunnels in both snapshots, skipped when this property is not specified

Sample configuration

The following configuration compares the state of IPSec tunnels as captured in snapshots.

This report produces the standardized dictionary.

reports = [
    {
        'ip_sec_tunnels': {
            'properties': ['state']
        }
    }
]

license​

Compares installed licenses. This report does not only check if we have the same set of licenses in both snapshots but also compares license details, such as expiration date, etc.

Method: SnapshotCompare.get_diff_and_threshold()

Configuration parameters

parameterdescription
properties(optional) a set of properties to skip when comparing two licenses, all properties are checked when this parameter is skipped
count_change_threshold(optional) maximum difference percentage of changed licenses in both snapshots, skipped when this property is not specified

Sample configuration

Following configuration is set to compare licenses as captured in snapshots. It will ignore the serial property.

This report produces the standardized dictionary.

reports = [
    {
        'license': {
            'properties': ['!serial']
        }
    }
]

nics​

Provides a report on status of network interfaces. This report is limited to information about network interfaces available in the snapshots. See the nics_snapshot snapshot information for details.

At the moment of writing this documentation, the snapshot contains only interface state information. Despite the fact that we use the generic method for preparing this report, the only reasonable parameter to use is count_change_threshold.

Method: SnapshotCompare.get_diff_and_threshold()

Configuration parameters

parameterdescription
count_change_threshold(optional) maximum difference percentage of changed network interfaces in both snapshots, skipped when this property is not specified

Sample configuration

The following configuration provides both: change in NICs\' state (implicitly) and maximum difference in NICs count (fail threshold is 10%).

This report produces the standardized dictionary.

reports = [
    {
        'nics': {
            'count_change_threshold': 10
        }
    }
]

routes​

Provides a report on differences between Route Table entries. It includes:

  • availability of a route in one of the snapshots,
  • for routes available in two snapshots, difference in route properties, such as age, next hop, etc.

Method: SnapshotCompare.get_diff_and_threshold()

Configuration parameters

parameterdescription
properties(optional) a set of properties to skip when comparing two routes, all properties are checked when this parameter is skipped
count_change_threshold(optional) maximum difference percentage of changed entries routes in both snapshots, skipped when this property is not specified

Sample configuration

The following configuration:

  • compares Route Table entries between both snapshots, but when comparing two entries the flags parameter is not taken into consideration,
  • calculates the count of changed Route Table entries from both snapshots and marks comparison as failed if the difference is bigger than 10%.

This report produces the standardized dictionary.

reports = [
    {
        'routes': {
            'properties': ['!flags'],
            'count_change_threshold': 10
        }
    }
]

session_stats​

This report is slightly different than reports made with the SnapshotCompare.get_diff_and_threshold() method as the snapshot data is different (refer to the FirewallProxy.get_session_stats() method documentation for details).

It takes one parameter only: thresholds. It contains a list of sessions stats as available in the snapshot. For each stat a threshold value is provided. This report calculates a change in the session statistics and compares it to the threshold value. This parameter does not have a default value - when skipped the report gives no results.

Method: SnapshotCompare.get_count_change_percentage()

Configuration parameters

parameterdescription
thresholdsa list of sessions with change threshold value to analyze

Sample configuration

The following configuration compares only stats for num-max and num-tcp. For both, the accepted difference is 10%.

This report produces a dict as documented in the SnapshotCompare.get_count_change_percentage() method documentation.

reports = [
    {
        'session_stats': {
            'thresholds': [
                {'num-max': 10},
                {'num-tcp': 10}
            ]
        }
    }
]

Health Checks​

Health checks are another category of check that look for specific issues or configuration that might either require an upgrade or impact the result of an upgrade.

Health checks represent checks that are boolean in nature. A result of such checks always presents a True/False value with some explanation in case of check fails. They can be triggered with a common method: CheckFirewall.run_health_checks(). When running this method, a list of health checks to run (with an optional configuration) is provided using the checks_configuration parameter. This list is defined using the ConfigParser class dialect. For details, refer to the documentation for this class.

Please see the sections below for details of each health check:

device_root_certificate_issue​

Checks if a device is impacted, or is to be impacted, by the expiration of the device root certificate.

This test by default checks only if the software version is an affected version and fails if it is.

If the fail_when_affected_version_only parameter is set to False, however, it will check to see if the issue is corrected by the device running and updated content version.

Method: CheckFirewall.check_arp_entry()

Configuration parameters

parameterdescription
fail_when_affected_version_only(Optional - Default 'True') Fails this test whenever the PAN-OS version is affected, regardless of the impact of the issue.