From 5093f787a051c012129064d48ae6385c6cc5488a Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" Date: Fri, 16 Feb 2024 12:41:51 +0000 Subject: [PATCH] docs: PanOS Upgrade Assurance documentation update --- .../api/check_firewall.md | 78 +++++++++++++-- .../api/firewall_proxy.md | 94 ++++++++++++++++--- .../api/snapshot_compare.md | 12 +-- .../configuration_details.mdx | 81 +++++++++++++++- 4 files changed, 235 insertions(+), 30 deletions(-) diff --git a/products/panos/docs/panos-upgrade-assurance/api/check_firewall.md b/products/panos/docs/panos-upgrade-assurance/api/check_firewall.md index c189cade7..72dc44c42 100644 --- a/products/panos/docs/panos-upgrade-assurance/api/check_firewall.md +++ b/products/panos/docs/panos-upgrade-assurance/api/check_firewall.md @@ -672,7 +672,7 @@ This method provides a convenient way of running health check methods. For detai __Parameters__ -- __checks_configuration__ (`list(str,dict), optional`): (defaults to `None`) List of readiness checks to run. +- __checks_configuration__ (`list(str,dict), optional`): (defaults to `None`) List of health checks to run. - __report_style__ (`bool`): (defaults to `False`) Changes the output to more descriptive. Can be used when generating a report from the checks. @@ -686,6 +686,34 @@ __Returns__ `dict`: Results of all configured checks. +### `CheckFirewall.check_version_against_version_match_dict` + +```python +@staticmethod +def check_version_against_version_match_dict(version: Version, + match_dict: dict) -> bool +``` + +Compare the given software version against the match dict. + +__Parameters__ + + +- __version__ (`Version`): The software version to compare (e.g. "10.1.11"). +- __match_dict__ (`dict`): A dictionary of tuples mapping major/minor versions to match criteria: + +```python showLineNumbers title="Example" +{ + "81": [("==", "8.1.21.2"), (">=", "8.1.25.1")], + "90": [(">=", "9.0.16.5")], +} +``` + +__Returns__ + + +`bool`: `True` If the given software version matches the provided match criteria + ### `CheckFirewall.check_device_root_certificate_issue` ```python @@ -693,17 +721,18 @@ def check_device_root_certificate_issue( fail_when_affected_version_only: bool = True) -> CheckResult ``` -Checks whether the target device is affected by the Root Certificate Expiration issue; +Checks whether the target device is affected by the [Root Certificate Expiration][live-564672] issue. -https://live.paloaltonetworks.com/t5/customer-advisories/emergency-update-required-pan-os-root-and-default-certificate/ta-p/564672 +[live-564672]: https://live.paloaltonetworks.com/t5/customer-advisories/emergency-update-required-pan-os-root-and-default-certificate/ta-p/564672 This check will FAIL if so, allowing you to build upgrade logic based on when and how it's failed. -This check will fail in the following scenarios; - 1. The device is running software that is affected by the issue AND is running out of date content - AND is NOT running the user-id service or data redistribution - 2. The device is running software that is affected by the issue AND IS running user-id service OR data - redistribution +This check will fail in the following scenarios: + +1. The device is running software that is affected by the issue AND is running out of date content + AND is NOT running the user-id service or data redistribution +2. The device is running software that is affected by the issue AND IS running user-id service OR data + redistribution __Parameters__ @@ -712,3 +741,36 @@ __Parameters__ fail if the software version is affected by the root certificate issue, AND the device is used for data redistribution OR it's using an out-of-date content DB version. +__Returns__ + + +`CheckResult`: Object of [`CheckResult`](/panos/docs/panos-upgrade-assurance/api/utils#class-checkresult) class taking value of: + +* [`CheckStatus.SUCCESS`](/panos/docs/panos-upgrade-assurance/api/utils#class-checkstatus) if the device is not affected, +* [`CheckStatus.FAIL`](/panos/docs/panos-upgrade-assurance/api/utils#class-checkstatus) otherwise. + +### `CheckFirewall.check_cdss_and_panorama_certificate_issue` + +```python +def check_cdss_and_panorama_certificate_issue() -> CheckResult +``` + +Checks whether the device is affected by the [PAN-OS Certificate Expirations Jan 2024 advisory][live-572158]. + +[live-572158]: https://live.paloaltonetworks.com/t5/customer-advisories/additional-pan-os-certificate-expirations-and-new-comprehensive/ta-p/572158 + +Check will fail in either of following scenarios: + + * Device is running an affected software version + * Device is running an affected content version + * Device is running the fixed content version or higher but has not been rebooted - note this is best effort, + and is based on when the content version was released and the device was rebooted + +__Returns__ + + +`CheckResult`: Object of [`CheckResult`](/panos/docs/panos-upgrade-assurance/api/utils#class-checkresult) class taking value of: + +* [`CheckStatus.SUCCESS`](/panos/docs/panos-upgrade-assurance/api/utils#class-checkstatus) if the device is not affected, +* [`CheckStatus.FAIL`](/panos/docs/panos-upgrade-assurance/api/utils#class-checkstatus) otherwise. + diff --git a/products/panos/docs/panos-upgrade-assurance/api/firewall_proxy.md b/products/panos/docs/panos-upgrade-assurance/api/firewall_proxy.md index 67db53fb6..f2f716fc1 100644 --- a/products/panos/docs/panos-upgrade-assurance/api/firewall_proxy.md +++ b/products/panos/docs/panos-upgrade-assurance/api/firewall_proxy.md @@ -106,6 +106,7 @@ __Raises__ __Returns__ + `dict, xml.etree.ElementTree.Element`: The actual command output. A type is defined by the `return_xml` parameter. ### `FirewallProxy.get_parser` @@ -136,6 +137,7 @@ __Raises__ __Returns__ + `dict, xml.etree.ElementTree.Element`: The actual command output. A type is defined by the `return_xml` parameter. ### `FirewallProxy.is_pending_changes` @@ -504,19 +506,20 @@ Get route table entries, either retrieved from DHCP or configured manually. The actual API command is `show routing route`. -In the returned `dict` the key is made of three route properties delimited with an underscore (`_`) in the following +In the returned `dict` the key is made of four route properties delimited with an underscore (`_`) in the following order: * virtual router name, * destination CIDR, -* network interface name if one is available, empty string otherwise. +* network interface name if one is available, empty string otherwise, +* next-hop address or name. The key does not provide any meaningful information, it's there only to introduce uniqueness for each entry. All properties that make a key are also available in the value of a dictionary element. ```python showLineNumbers title="Sample output" { - private_0.0.0.0/0_private/i3': { + private_0.0.0.0/0_private/i3_vr-public': { 'age': None, 'destination': '0.0.0.0/0', 'flags': 'A S', @@ -526,7 +529,7 @@ properties that make a key are also available in the value of a dictionary eleme 'route-table': 'unicast', 'virtual-router': 'private' }, - 'public_10.0.0.0/8_public/i3': { + 'public_10.0.0.0/8_public/i3_vr-private': { 'age': None, 'destination': '10.0.0.0/8', 'flags': 'A S', @@ -1145,10 +1148,10 @@ Get the status of the User ID agent service. The user-id service is used to redistribute user-id information to other firewalls. -__Returns the clients and agents known to this device.__ +__Returns__ -dict: The state of the user-id agent. Only returns up or down. +`dict`: The state of the user-id agent. Only returns up or down. ```python showLineNumbers title="Sample output" { @@ -1164,12 +1167,12 @@ def get_redistribution_status() -> dict Get the status of the Data Redistribution service. -Redistribution is used to share data, such as user-id information, between PAN-OS firewalls or Agents. +Redistribution service is used to share data, such as user-id information, between PAN-OS firewalls or Agents. -__Returns the clients and agents known to this device.__ +__Returns__ -dict: The state of the redistribution service, and the associated clients, if available. +`dict`: The state of the redistribution service, and the associated clients, if available. ```python showLineNumbers title="Sample output" { @@ -1209,13 +1212,78 @@ dict: The state of the redistribution service, and the associated clients, if av def get_device_software_version() ``` -Gets the current running device software version, as a packaging.version.Version object. +Gets the current running device software version, as a `packaging.version.Version` object. This allows you to do comparators between other Version objects easily. Note that this strips out information - like 'xfr' but maintains the hotfix (i.e 9.1.12-h3 becaomes 9.1.12.3 for the purpose of versioning). + like `xfr` but maintains the hotfix (i.e `9.1.12-h3` becomes `9.1.12.3` for the purpose of versioning). + +__Returns__ + + +`Version`: the software version as a packaging 'Version' object. -__Returns the software version as a packaging 'Version' object.__ +### `FirewallProxy.get_fib` + +```python +def get_fib() -> dict +``` +Get the information from the forwarding information table (FIB). + +The actual API command run is `show routing fib`. + +In the returned `dict` the key is made of three route properties delimited with an underscore (`_`) in the following +order: + +* destination CIDR, +* network interface name, +* next-hop address or name. + +The key does not provide any meaningful information, it's there only to introduce uniqueness for each entry. All +properties that make a key are also available in the value of a dictionary element. + +__Returns__ -Version: Version(9.1.12) + +`dict`: Status of the route entries in the FIB + +```python showLineNumbers title="Sample output" +{ + '0.0.0.0/0_ethernet1/1_10.10.11.1': { + 'Destination': '0.0.0.0/0', + 'Interface': 'ethernet1/1', + 'Next Hop Type': '0', + 'Flags': 'ug', + 'Next Hop': '10.10.11.1', + 'MTU': '1500' + }, + '1.1.1.1/32_loopback.10_0.0.0.0': { + 'Destination': '1.1.1.1/32', + 'Interface': 'loopback.10', + 'Next Hop Type': '3', + 'Flags': 'uh', + 'Next Hop': '0.0.0.0', + 'MTU': '1500' + } +} +``` + +### `FirewallProxy.get_system_time_rebooted` + +```python +def get_system_time_rebooted() -> datetime +``` + +Returns the date and time the system last rebooted using the system uptime. + +The actual API command is `show system info`. + +__Returns__ + + +`datetime`: Time system was last rebooted based on current time - system uptime string + +```python showLineNumbers title="Sample output" +datetime(2024, 01, 01, 00, 00, 00) +``` diff --git a/products/panos/docs/panos-upgrade-assurance/api/snapshot_compare.md b/products/panos/docs/panos-upgrade-assurance/api/snapshot_compare.md index 3a0fa8297..9ca0ec0a9 100644 --- a/products/panos/docs/panos-upgrade-assurance/api/snapshot_compare.md +++ b/products/panos/docs/panos-upgrade-assurance/api/snapshot_compare.md @@ -202,7 +202,7 @@ when comparing route tables snapshots are formatted like: ```python showLineNumbers { "routes": { - "default_0.0.0.0/0_ethernet1/3": { + "default_0.0.0.0/0_ethernet1/3_10.26.129.129": { "virtual-router": "default", "destination": "0.0.0.0/0", "nexthop": "10.26.129.129", @@ -376,7 +376,7 @@ To illustrate that, the `passed` flag added by this method is highlighted: }, 'missing': { 'missing_keys': [ - 'default_0.0.0.0/0_ethernet1/3' + 'default_0.0.0.0/0_ethernet1/3_10.26.129.129' ], 'passed': False }, @@ -427,21 +427,21 @@ An example for the route tables, crafted in a way that almost each level fails: { "added": { "added_keys": [ - "default_10.26.129.0/25_ethernet1/2", - "default_168.63.129.16/32_ethernet1/3" + "default_10.26.129.0/25_ethernet1/2_10.26.129.1", + "default_168.63.129.16/32_ethernet1/3_10.26.129.129" ], "passed": "False" }, "missing": { "missing_keys": [ - "default_0.0.0.0/0_ethernet1/3" + "default_0.0.0.0/0_ethernet1/3_10.26.129.129" ], "passed": "False" }, "changed": { # highlight-start "changed_raw": { - "default_10.26.130.0/25_ethernet1/2": { + "default_10.26.130.0/25_ethernet1/2_10.26.129.1": { "added": { "added_keys": [], "passed": "True" diff --git a/products/panos/docs/panos-upgrade-assurance/configuration_details.mdx b/products/panos/docs/panos-upgrade-assurance/configuration_details.mdx index b6ce0e0b5..5cfe117a0 100644 --- a/products/panos/docs/panos-upgrade-assurance/configuration_details.mdx +++ b/products/panos/docs/panos-upgrade-assurance/configuration_details.mdx @@ -919,7 +919,7 @@ The sample output containing a snapshot for *route tables*, *licenses*, and *IPS }, }. "routes": { - "default_0.0.0.0/0_ethernet1/3": { + "default_0.0.0.0/0_ethernet1/3_10.26.129.129": { "virtual-router": "default", "destination": "0.0.0.0/0", "nexthop": "10.26.129.129", @@ -966,6 +966,7 @@ snapshots_config = [ 'content_version', 'session_stats', 'ip_sec_tunnels', + 'fib_routes', ] ``` @@ -983,6 +984,7 @@ snapshots_config: - content_version - session_stats - ip_sec_tunnels + - fib_routes ``` ```mdx-code-block @@ -1028,6 +1030,12 @@ Takes a snapshot of the Route Table (this includes routes populated from DHCP as **Method:** [`FirewallProxy.get_routes()`](/panos/docs/panos-upgrade-assurance/api/firewall_proxy#firewallproxyget_routes) +### `fib_routes` + +Takes a snapshot of the Forwarding table (routes that are actually taken into forwarding decisions based on routing table). + +**Method:** [`FirewallProxy.get_fib()`](/panos/docs/panos-upgrade-assurance/api/firewall_proxy#firewallproxyget_fib) + ### `session_stats` Gets information about the session statistics, such as current sessions count per a session type (TCP, UDP, etc). @@ -1064,6 +1072,10 @@ reports = [ 'properties': ['!flags'], 'count_change_threshold': 10 }}, + {'fib_routes': { + 'properties': ['!flags'], + 'count_change_threshold': 10 + }}, 'content_version', {'session_stats': { 'thresholds': [ @@ -1097,6 +1109,10 @@ reports: properties: - "!flags" count_change_threshold: 10 + - fib_routes: + properties: + - "!flags" + count_change_threshold: 10 - content_version - session_stats: thresholds: @@ -1393,6 +1409,65 @@ reports: ``` +### `fib_routes` + +Provides a report on differences between FIB Table entries. It includes: + +- availability of a fib entry in one of the snapshots, +- for fib entries available in two snapshots, difference in fib entry properties, such as destination, next hop, flags etc. + +**Method:** [`SnapshotCompare.get_diff_and_threshold()`](/panos/docs/panos-upgrade-assurance/api/snapshot_compare#snapshotcompareget_diff_and_threshold) + +**Configuration parameters** + +parameter | description +--- | --- +`properties` | (optional) a set of properties to skip when comparing two fib entries, all properties are checked when this parameter is skipped +`count_change_threshold` | (optional) maximum difference percentage of changed entries for fib routes in both snapshots, skipped when this property is not specified + +**Sample configuration** + +The following configuration: + +- compares FIB Table entries between both snapshots, but when comparing two entries the `flags` parameter is not taken into consideration, +- calculates the count of changed FIB Table entries from both snapshots and marks comparison as failed if the difference is bigger than 10%. + +This report produces the standardized dictionary. + +```mdx-code-block + + +``` + +```python showLineNumbers +reports = [ + { + 'fib_routes': { + 'properties': ['!flags'], + 'count_change_threshold': 10 + } + } +] +``` + +```mdx-code-block + + +``` + +```yaml showLineNumbers +reports: + - fib_routes: + properties: + - '!flags' + count_change_threshold: 10 +``` + +```mdx-code-block + + +``` + ### `session_stats` This report is slightly different than reports made with the [`SnapshotCompare.get_diff_and_threshold()`](/panos/docs/panos-upgrade-assurance/api/snapshot_compare#snapshotcompareget_diff_and_threshold) method as the snapshot data is different (refer to the [`FirewallProxy.get_session_stats()`](/panos/docs/panos-upgrade-assurance/api/firewall_proxy#firewallproxyget_session_stats) method documentation for details). @@ -1460,14 +1535,14 @@ 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.](https://knowledgebase.paloaltonetworks.com/KCSArticleDetail?id=kA14u0000008Vp5CAE) +Checks if a device is impacted, or is to be impacted, by the [expiration of the device root certificate](https://knowledgebase.paloaltonetworks.com/KCSArticleDetail?id=kA14u0000008Vp5CAE). 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()`](/panos/docs/panos-upgrade-assurance/api/check_firewall#checkfirewallcheck_arp_entry) +**Method:** [`CheckFirewall.check_device_root_certificate_issue()`](/panos/docs/panos-upgrade-assurance/api/check_firewall#checkfirewallcheck_device_root_certificate_issue) **Configuration parameters**