docs: PanOS Upgrade Assurance documentation update (#562)

Co-authored-by: FoSix <[email protected]>

products/panos/docs/panos-upgrade-assurance.mdx

@@ -22,7 +22,7 @@ The `panos-upgrade-assurance` includes the set of libraries written in `Python`
 
 Both checks and snapshots can be used to verify the state of a device during an upgrade process. What more, it is possible to generate a report for these checks.
 
-The libraries were written to support Ansible and XSOAR integrations. They depend on [pan-os-python](/panos/docs/panospython/) libraries and therefore are quite easy to fit into the [PAN-OS Ansible modules collection](https://galaxy.ansible.com/ui/repo/published/paloaltonetworks/panos). Equivalent yaml configurations are provided in the documentation as a reference to use with the PAN-OS Ansible modules collection.
+The libraries were written to support Ansible and XSOAR integrations. They depend on [pan-os-python](/panos/docs/panospython/) libraries and therefore are quite easy to fit into the [PanOS Ansible modules collection](https://galaxy.ansible.com/paloaltonetworks/panos). Equivalent yaml configurations are provided in the documentation as a reference to use with the PanOS Ansible modules collection.
 
 The libraries are available in two form factors:
 

products/panos/docs/panos-upgrade-assurance/api/check_firewall.md

@@ -656,3 +656,59 @@ __Returns__
 
 `dict`: The results of the executed snapshots.
 
+### `CheckFirewall.run_health_checks`
+
+```python
+def run_health_checks(
+        checks_configuration: Optional[List[Union[str, dict]]] = None,
+        report_style: bool = False) -> Union[Dict[str, dict], Dict[str, str]]
+```
+
+Run device health checks.
+
+This method provides a convenient way of running health check methods. For details on configuration see the
+[health checks](/panos/docs/panos-upgrade-assurance/configuration-details#health-checks) documentation.
+
+__Parameters__
+
+
+- __checks_configuration__ (`list(str,dict), optional`): (defaults to `None`) List of readiness 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.
+
+__Raises__
+
+
+- `WrongDataTypeException`: An exception is raised when the configuration is in a data type different then `str` or `dict`.
+
+__Returns__
+
+
+`dict`: Results of all configured checks.
+
+### `CheckFirewall.check_device_root_certificate_issue`
+
+```python
+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;
+
+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
+
+__Parameters__
+
+
+- __fail_when_affected_version_only__ (`bool, optional`): (defaults to `True`) When set to False, this test will only
+    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.
+

products/panos/docs/panos-upgrade-assurance/api/firewall_proxy.md

@@ -1135,3 +1135,87 @@ __Returns__
     'warnings': None}}
 ```
 
+### `FirewallProxy.get_user_id_service_status`
+
+```python
+def get_user_id_service_status() -> dict
+```
+
+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.__
+
+
+dict: The state of the user-id agent. Only returns up or down.
+
+```python showLineNumbers title="Sample output"
+{
+    "status": "up"
+}
+```
+
+### `FirewallProxy.get_redistribution_status`
+
+```python
+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.
+
+__Returns the clients and agents known to this device.__
+
+
+dict: The state of the redistribution service, and the associated clients, if available.
+
+```python showLineNumbers title="Sample output"
+{
+    'clients': [
+        {
+            'host': '1.1.1.1', 'port': '34518', 'vsys': 'vsys1', 'version': '6', 'status': 'idle',
+            'redistribution': 'I'
+        },
+        {
+            'host': '1.1.1.2', 'port': '34518', 'vsys': 'vsys1', 'version': '6', 'status': 'idle',
+            'redistribution': 'I'
+        }
+    ],
+    'agents': [
+        {
+            '@name': 'FW3367',
+            'host': '1.1.1.1',
+            'job-id': '0',
+            'last-heard-time': '1701651677',
+            'num_recv_msgs': '0',
+            'num_sent_msgs': '0',
+            'peer-address': '1.1.1.1',
+            'port': '5007',
+            'state': 'conn:idle',
+            'status-msg': '-',
+            'version': '0x6',
+            'vsys': 'vsys1',
+            'vsys_hub': 'no'
+        }
+    ]
+}
+```
+
+### `FirewallProxy.get_device_software_version`
+
+```python
+def get_device_software_version()
+```
+
+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).
+
+__Returns the software version as a packaging 'Version' object.__
+
+
+Version: Version(9.1.12)
+

products/panos/docs/panos-upgrade-assurance/api/utils.md

@@ -25,6 +25,16 @@ strings. These strings are compared in several places to parse the configuration
 This class is used to avoid hardcoding these strings. It maps the actual configuration string to a variable that can be
 referenced in the code.
 
+## class `HealthType`
+
+Class mapping the health check configuration strings to commonly used variables.
+
+[`CheckFirewall`](/panos/docs/panos-upgrade-assurance/api/check_firewall#class-checkfirewall) class is in a form of a list of
+strings. These strings are compared in several places to parse the configuration.
+
+This class is used to avoid hardcoding these strings. It maps the actual configuration string to a variable that can be
+referenced in the code.
+
 ## class `CheckStatus`
 
 Class containing possible statuses for the check results.

products/panos/docs/panos-upgrade-assurance/configuration_details.mdx

@@ -1449,6 +1449,33 @@ reports:
 </Tabs>
 ```
 
+## 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()`](/panos/docs/panos-upgrade-assurance/api/check_firewall#checkfirewallrun_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`][cfgprs] class [`dialect`][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.](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)
+
+**Configuration parameters**
+
+parameter | description
+--- | ---
+`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.
+
+
 [cfgprs]: /panos/docs/panos-upgrade-assurance/api/utils#class-configparser
 [chckres]: /panos/docs/panos-upgrade-assurance/api/utils#class-checkresult
 [dialect]: /panos/docs/panos-upgrade-assurance/dialect