Merge branch 'main' into 108-refactor-multi-level-snapshot-comparison

.github/workflows/_discover_python_ver.yml

@@ -22,7 +22,7 @@ jobs:
       pyversion: ${{ steps.pyversion.outputs.pyversion }}
     steps:
       - name: checkout code
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
       - name: discover Python version
         id: pyversion
         uses: ./.github/actions/discover_python_version

.github/workflows/_docker.yml

@@ -29,7 +29,7 @@ jobs:
       contents: read
     steps:
       - name: checkout code
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
         with:
           ref: ${{ inputs.tag_name }}
 
@@ -55,7 +55,7 @@ jobs:
 
       - name: determine docker tags and labels
         id: meta
-        uses: docker/metadata-action@v4
+        uses: docker/metadata-action@v5
         with:
           images: ghcr.io/paloaltonetworks/panos_upgrade_assurance
           tags: |
@@ -66,14 +66,14 @@ jobs:
 
       - name: login to GHCR
         if: inputs.publish
-        uses: docker/login-action@v2
+        uses: docker/login-action@v3
         with:
           registry: ghcr.io
           username: ${{ github.actor }}
           password: ${{ secrets.GITHUB_TOKEN }}
 
       - name: build ${{ inputs.publish && 'and publish' || '' }}
-        uses: docker/build-push-action@v4
+        uses: docker/build-push-action@v5
         with:
           context: .
           push: ${{ inputs.publish }}

.github/workflows/pr.yml

@@ -65,7 +65,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: checkout code
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
       - name: pack the documentation
         working-directory: docs
         run: tar --exclude .DS_Store --exclude sidebars.js -cvf documentation.tar *
@@ -84,7 +84,7 @@ jobs:
       pull-requests: write
     steps:
       - name: checkout pan.dev
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
         with:
           repository: PaloAltoNetworks/pan.dev
           token: ${{ secrets.CLSC_PAT }}

.github/workflows/publish_documentation.yml

@@ -52,7 +52,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: checkout code
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
       - name: pack the documentation
         working-directory: docs
         run: tar --exclude .DS_Store --exclude sidebars.js -cvf documentation.tar *
@@ -73,7 +73,7 @@ jobs:
       pull-requests: write
     steps:
       - name: checkout pan.dev
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
         with:
           repository: PaloAltoNetworks/pan.dev
           token: ${{ secrets.CLSC_PAT }}

.github/workflows/publish_python_package.yml

@@ -19,7 +19,7 @@ jobs:
     needs: pyversion
     steps:
       - name: Checkout code
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
 
       - name: Install Python
         uses: actions/setup-python@v4

.github/workflows/release.yml

@@ -22,11 +22,11 @@ jobs:
       ver: ${{ steps.rc.outputs.new_release_version }}
     steps:
       - name: Checkout code
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
 
       - name: Check if new version will be produced
         id: rc
-        uses: cycjimmy/semantic-release-action@v3
+        uses: cycjimmy/semantic-release-action@v4
         with:
           dry_run: true
           semantic_version: 19.0
@@ -83,7 +83,7 @@ jobs:
       tag: ${{ steps.release.outputs.new_release_git_tag }}
     steps:
       - name: Checkout code
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
 
       - name: Install Python
         uses: actions/setup-python@v4
@@ -105,11 +105,11 @@ jobs:
 
       - name: Create release and publish to GitHub
         id: release
-        uses: cycjimmy/semantic-release-action@v3
+        uses: cycjimmy/semantic-release-action@v4
         with:
           semantic_version: 19.0
           extra_plugins: |
             conventional-changelog-conventionalcommits@^5.0.0
             @semantic-release/git@^10.0.1
         env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GITHUB_TOKEN: ${{ secrets.RELEASE_PAT }}

.github/workflows/sub_docs.yml

@@ -19,7 +19,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout code
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
 
       - name: Install Python
         uses: actions/setup-python@v4

.github/workflows/sub_format.yml

@@ -18,7 +18,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout code
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
 
       - name: Install Python
         uses: actions/setup-python@v4

.github/workflows/sub_unittest.yml

@@ -19,7 +19,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout code
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
 
       - name: Install Python
         uses: actions/setup-python@v4

.gitignore

@@ -59,5 +59,6 @@ poetry.lock
 sidebar.json
 .python-version
 requirements.txt
+openssl.cnf
 .coverage
 coverage.xml

Makefile

@@ -1,21 +1,28 @@
+.phony: lint
 lint:
 	flake8 panos_upgrade_assurance tests
 
+.phony: security
 security:
 	bandit -c pyproject.toml -r .
 
+.phony: format_check
 format_check:
 	black --diff --check panos_upgrade_assurance tests
 
+.phony: format
 format:
 	black panos_upgrade_assurance tests
 
+.phony: test_coverage
 test_coverage:
 	pytest --cov panos_upgrade_assurance --cov-report=term-missing --cov-report=xml:coverage.xml
 
+.phony: documentation
 documentation:
 	pydoc-markdown
 
+.phony: check_line_length
 check_line_length:
 	@for FILE in $$(find . -type f -name '*.py'); do \
 		echo $$FILE; \
@@ -29,4 +36,8 @@ check_line_length:
 		done < "$$FILE"; \
 	done
 
+.phony: all
 all: lint format security test_coverage documentation
+
+.phony: sca
+sca: format lint security

README.md

@@ -1,3 +1,11 @@
+![GitHub release (latest by date)](https://img.shields.io/github/v/release/PaloAltoNetworks/pan-os-upgrade-assurance?style=flat-square)
+![GitHub](https://img.shields.io/github/license/PaloAltoNetworks/terraform-modules-vmseries-ci-workflows?style=flat-square)
+![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/PaloAltoNetworks/pan-os-upgrade-assurance/release.yml?style=flat-square)
+![GitHub issues](https://img.shields.io/github/issues/PaloAltoNetworks/pan-os-upgrade-assurance?style=flat-square)
+![GitHub pull requests](https://img.shields.io/github/issues-pr/PaloAltoNetworks/pan-os-upgrade-assurance?style=flat-square)
+![PyPI - Downloads](https://img.shields.io/pypi/dm/panos-upgrade-assurance?style=flat-square)
+
+
 # PAN-OS Upgrade Assurance
 
 ## Overview

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 [PanOS Ansible modules collection](https://galaxy.ansible.com/paloaltonetworks/panos).
+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:
 

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

@@ -459,6 +459,96 @@ __Returns__
 * [`CheckStatus.ERROR`](/panos/docs/panos-upgrade-assurance/api/utils#class-checkstatus) when the certificate's
     properties (installed or required) are not supported.
 
+### `CheckFirewall._calculate_schedule_time_diff`
+
+```python
+def _calculate_schedule_time_diff(now_dt: datetime, schedule_type: str,
+                                  schedule: dict) -> (int, str)
+```
+
+A method that calculates the time distance between two `datetime` objects.
+
+:::note
+This method is used only by [`CheckFirewall.check_scheduled_updates()`](#checkfirewallcheck_scheduled_updates) method and it expects some information
+to be already available.
+:::
+
+__Parameters__
+
+
+- __now_dt__ (`datetime`): A `datetime` object representing the current moment in time. Ideally this should be the device's local
+    time, taken from the management plane clock.
+- __schedule_type__ (`str`): A schedule type returned by PanOS, can be one of: `every-*`, `hourly`, `daily`, `weekly`,
+    `real-time`.
+- __schedule__ (`dict`): Value of the `recurring` key in the API response, see
+    [`FirewallProxy.get_update_schedules()`](/panos/docs/panos-upgrade-assurance/api/firewall_proxy#firewallproxyget_update_schedules)
+    documentation for details. Both formats (locally configured and pushed from a Panorama template) are supported.
+
+__Raises__
+
+
+- `MalformedResponseException`: Thrown then the `schedule_type` is not recognizable.
+
+__Returns__
+
+
+`tuple(int, str)`: A tuple containing the calculated time difference (in minutes) and human-readable description.
+
+### `CheckFirewall.check_scheduled_updates`
+
+```python
+def check_scheduled_updates(test_window: int = 60) -> CheckResult
+```
+
+Check if any Dynamic Update job is scheduled to run within the specified time window.
+
+When device is configured via Panorama, this includes schedules set up in Templates. It does not however include schedules
+configured in `Panorama/Device Deployment/Dynamic Updates/Schedules`.
+
+__Parameters__
+
+
+- __test_window__ (`int, optional`): (defaults to 60 minutes). A time window in minutes to look for an update job occurrence.
+    Has to be a value between `60` and `10080` (1 week equivalent). The time window is calculated based on the device's
+    local time (taken from the management plane).
+
+__Raises__
+
+
+- `MalformedResponseException`: Thrown in case API response does not meet expectations.
+
+__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) when there is no update job
+    planned within the test window.
+* [`CheckStatus.FAIL`](/panos/docs/panos-upgrade-assurance/api/utils#class-checkstatus) otherwise, `CheckResult.reason`
+    field contains information about the planned jobs with next occurrence time provided if possible.
+* [`CheckStatus.ERROR`](/panos/docs/panos-upgrade-assurance/api/utils#class-checkstatus) when the `test_window` parameter
+    does not meet criteria.
+
+### `CheckFirewall.check_non_finished_jobs`
+
+```python
+def check_non_finished_jobs() -> CheckResult
+```
+
+Check for any job with status different than FIN.
+
+__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) when all jobs are in FIN state.
+* [`CheckStatus.FAIL`](/panos/docs/panos-upgrade-assurance/api/utils#class-checkstatus) otherwise, `CheckResult.reason`
+    field contains information about the 1<sup>st</sup> job found with status different than FIN (job ID and the actual
+    status).
+* [`CheckStatus.SKIPPED`](/panos/docs/panos-upgrade-assurance/api/utils#class-checkstatus) when there are no jobs on a
+    device.
+
 ### `CheckFirewall.get_content_db_version`
 
 ```python

docs/panos-upgrade-assurance/api/exceptions.md

@@ -28,10 +28,19 @@ module.
 
 Parent class for all exceptions coming from [Utils](/panos/docs/panos-upgrade-assurance/api/utils) module.
 
+## class `WrongNumberOfArgumentsException`
+
+Thrown when [FirewallProxy](/panos/docs/panos-upgrade-assurance/api/firewall_proxy) constructor is given wrong number or
+set of arguments.
+
 ## class `CommandRunFailedException`
 
 Used when a command run on a device does not return the `success` status.
 
+## class `GetXpathConfigFailedException`
+
+Used when XAPI does not return a `success` state when running a `get` operation.
+
 ## class `MalformedResponseException`
 
 A generic exception class used when a response does not meet the expected standards.