diff --git a/products/panos/docs/panos-upgrade-assurance.mdx b/products/panos/docs/panos-upgrade-assurance.mdx index cf1f600c9..bbf785166 100644 --- a/products/panos/docs/panos-upgrade-assurance.mdx +++ b/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: 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 d3197b581..c189cade7 100644 --- a/products/panos/docs/panos-upgrade-assurance/api/check_firewall.md +++ b/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. + 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 ef5cb260c..67db53fb6 100644 --- a/products/panos/docs/panos-upgrade-assurance/api/firewall_proxy.md +++ b/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) + diff --git a/products/panos/docs/panos-upgrade-assurance/api/utils.md b/products/panos/docs/panos-upgrade-assurance/api/utils.md index c8247af07..f2509ab2b 100644 --- a/products/panos/docs/panos-upgrade-assurance/api/utils.md +++ b/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. diff --git a/products/panos/docs/panos-upgrade-assurance/configuration_details.mdx b/products/panos/docs/panos-upgrade-assurance/configuration_details.mdx index 2f378415c..b6ce0e0b5 100644 --- a/products/panos/docs/panos-upgrade-assurance/configuration_details.mdx +++ b/products/panos/docs/panos-upgrade-assurance/configuration_details.mdx @@ -1449,6 +1449,33 @@ reports: ``` +## 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