Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[PAN-OS Upgrade Assurance][dependabot/github_actions/actions/setup-python-5] documentation PREVIEW - do NOT MERGE #614

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

[PAN-OS Upgrade Assurance][dependabot/github_actions/actions/setup-python-5] documentation PREVIEW - do NOT MERGE #614

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
78 changes: 70 additions & 8 deletions products/panos/docs/panos-upgrade-assurance/api/check_firewall.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand All @@ -686,24 +686,53 @@ __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
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__

Expand All @@ -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.

94 changes: 81 additions & 13 deletions products/panos/docs/panos-upgrade-assurance/api/firewall_proxy.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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`
Expand Down Expand Up @@ -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`
Expand Down Expand Up @@ -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',
Expand All @@ -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',
Expand Down Expand Up @@ -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"
{
Expand All @@ -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"
{
Expand Down Expand Up @@ -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)
```

12 changes: 6 additions & 6 deletions products/panos/docs/panos-upgrade-assurance/api/snapshot_compare.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down Expand Up @@ -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
},
Expand Down Expand Up @@ -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"
Expand Down
Loading
Loading