Python script to automate the upgrade process of PAN-OS firewalls.
Project description
PAN-OS Automation Project
Streamlining Palo Alto Networks Firewall Upgrades with Python Automation
Explore the docs ยป
View Demo
Report Bug
Request Feature
Table of Contents
About The Project
This project is a comprehensive Python-based solution for automating PAN-OS upgrades. It's designed to provide network administrators and security professionals with an efficient tool to manage upgrades, configurations, and system checks of Palo Alto Networks appliances.
Key Features
- Automation of Routine Tasks: Reduces manual errors and saves time by automating upgrades, configurations, and system checks.
- Support for Direct and Proxy Connections: Connect directly to firewalls or through a Panorama appliance, with support for targeting specific devices using filters.
- Active/Passive High Availability (HA) Workflow: Fully supports upgrading devices in active/passive HA configurations, ensuring both members are properly upgraded and synchronized.
- Multi-threading for Efficiency: Utilizes multi-threading to parallelize upgrades, especially beneficial when upgrading multiple devices through Panorama, enhancing performance and reducing overall upgrade time.
- Customizable and Extensible: Scripts can be tailored to fit diverse network environments and requirements, offering flexibility for various deployment scenarios.
- Comprehensive PAN-OS Interactions: Facilitates extensive interactions with Palo Alto Networks appliances for operations like readiness checks, state snapshots, and report generation.
Note: While this script is optimized for standalone and active/passive HA environments, it has not been tested against active/active or clustered firewalls.
Example Execution
$ pan-os-upgrade
Hostname or IP: panorama.cdot.io
Username: cdot
Password:
Target PAN-OS version: 10.2.2-h2
Filter string (only applicable for Panorama) []: hostname=Woodlands*
โ
panorama.cdot.io: Connection to Panorama established. Firewall connections will be proxied!
๐ Woodlands-fw1: 007954000123451 192.168.255.43
๐ Woodlands-fw2: 007954000123452 192.168.255.44
๐ Woodlands-fw1: HA mode: passive
๐ Woodlands-fw2: HA mode: active
๐ Woodlands-fw2: Detected active firewall in HA pair running the same version as its peer. Added firewall to revisit list.
๐ Woodlands-fw1: Current PAN-OS version: 10.2.2
๐ Woodlands-fw1: Target PAN-OS version: 10.2.2-h2
โ
Woodlands-fw1: Upgrade required from 10.2.2 to 10.2.2-h2
โ
Woodlands-fw1: PAN-OS version 10.2.2-h2 is available for download
โ
Woodlands-fw1: Base image for 10.2.2-h2 is already downloaded
๐ Woodlands-fw1: Performing test to see if 10.2.2-h2 is already downloaded...
๐ Woodlands-fw1: PAN-OS version 10.2.2-h2 is not on the firewall
๐ Woodlands-fw1: PAN-OS version 10.2.2-h2 is beginning download
Device 007954000123451 downloading version: 10.2.2-h2
๐ง Woodlands-fw1: Downloading PAN-OS version 10.2.2-h2 - HA will sync image - Elapsed time: 5 seconds
๐ง Woodlands-fw1: Downloading PAN-OS version 10.2.2-h2 - HA will sync image - Elapsed time: 37 seconds
๐ง Woodlands-fw1: Downloading PAN-OS version 10.2.2-h2 - HA will sync image - Elapsed time: 68 seconds
๐ง Woodlands-fw1: Downloading PAN-OS version 10.2.2-h2 - HA will sync image - Elapsed time: 100 seconds
๐ง Woodlands-fw1: Downloading PAN-OS version 10.2.2-h2 - HA will sync image - Elapsed time: 133 seconds
๐ง Woodlands-fw1: Downloading PAN-OS version 10.2.2-h2 - HA will sync image - Elapsed time: 167 seconds
โ
Woodlands-fw1: 10.2.2-h2 downloaded in 199 seconds
โ
Woodlands-fw1: 10.2.2-h2 has been downloaded and sync'd to HA peer.
๐ Woodlands-fw1: Performing snapshot of network state information...
โ
Woodlands-fw1: Network snapshot created successfully
๐ Woodlands-fw1: Performing readiness checks to determine if firewall is ready for upgrade...
โ
Woodlands-fw1: Passed Readiness Check: Check if there are pending changes on device
โ
Woodlands-fw1: Passed Readiness Check: No Expired Licenses
โ
Woodlands-fw1: Passed Readiness Check: Checks HA pair status from the perspective of the current device
โ
Woodlands-fw1: Passed Readiness Check: Check if NTP is synchronized
โ
Woodlands-fw1: Passed Readiness Check: Check connectivity with the Panorama appliance
โ
Woodlands-fw1: Readiness Checks completed
๐ Woodlands-fw1: Checking if HA peer is in sync...
โ
Woodlands-fw1: HA peer sync test has been completed.
๐ Woodlands-fw1: Performing backup of configuration to local filesystem...
๐ Woodlands-fw1: Not a dry run, continue with upgrade...
๐ Woodlands-fw1: Performing upgrade to version 10.2.2-h2...
๐ Woodlands-fw1: Attempting upgrade to version 10.2.2-h2 (Attempt 1 of 3)...
Device 007954000123451 installing version: 10.2.2-h2
โ
Woodlands-fw1: Upgrade completed successfully
๐ Woodlands-fw1: Rebooting the passive HA firewall...
๐ Woodlands-fw1: Command succeeded with no output
๐ง Woodlands-fw1: Firewall is rebooting...
๐ง Woodlands-fw1: Firewall is rebooting...
๐ง Woodlands-fw1: Firewall is rebooting...
๐ง Woodlands-fw1: Firewall is rebooting...
๐ง Woodlands-fw1: Firewall is rebooting...
๐ง Woodlands-fw1: Firewall is rebooting...
๐ง Woodlands-fw1: Firewall is rebooting...
โ
Woodlands-fw1: HA passive firewall rebooted and synchronized with its peer in 499 seconds
๐ panorama.cdot.io: Revisiting firewalls that were active in an HA pair and had the same version as their peers.
๐ Woodlands-fw2: 007954000123452 192.168.255.44
๐ Woodlands-fw2: HA mode: active
โ Woodlands-fw2: Error suspending active firewall HA state: argument of type 'NoneType' is not iterable
๐ Woodlands-fw2: Current PAN-OS version: 10.2.2
๐ Woodlands-fw2: Target PAN-OS version: 10.2.2-h2
โ
Woodlands-fw2: Upgrade required from 10.2.2 to 10.2.2-h2
โ
Woodlands-fw2: PAN-OS version 10.2.2-h2 is available for download
โ
Woodlands-fw2: Base image for 10.2.2-h2 is already downloaded
๐ Woodlands-fw2: Performing test to see if 10.2.2-h2 is already downloaded...
โ
Woodlands-fw2: PAN-OS version 10.2.2-h2 already on firewall.
โ
Woodlands-fw2: 10.2.2-h2 has been downloaded and sync'd to HA peer.
๐ Woodlands-fw2: Performing snapshot of network state information...
โ
Woodlands-fw2: Network snapshot created successfully
๐ Woodlands-fw2: Performing readiness checks to determine if firewall is ready for upgrade...
โ
Woodlands-fw2: Passed Readiness Check: Check if there are pending changes on device
โ
Woodlands-fw2: Passed Readiness Check: No Expired Licenses
โ
Woodlands-fw2: Passed Readiness Check: Check if NTP is synchronized
โ
Woodlands-fw2: Passed Readiness Check: Check connectivity with the Panorama appliance
โ
Woodlands-fw2: Readiness Checks completed
๐ Woodlands-fw2: Checking if HA peer is in sync...
โ
Woodlands-fw2: HA peer sync test has been completed.
๐ Woodlands-fw2: Performing backup of configuration to local filesystem...
๐ Woodlands-fw2: Not a dry run, continue with upgrade...
๐ Woodlands-fw2: Performing upgrade to version 10.2.2-h2...
๐ Woodlands-fw2: Attempting upgrade to version 10.2.2-h2 (Attempt 1 of 3)...
Device 007954000123452 installing version: 10.2.2-h2
โ
Woodlands-fw2: Upgrade completed successfully
๐ Woodlands-fw2: Rebooting the passive HA firewall...
๐ Woodlands-fw2: Command succeeded with no output
๐ง Woodlands-fw2: Firewall is rebooting...
๐ง Woodlands-fw2: Firewall is rebooting...
๐ง Woodlands-fw2: Firewall is rebooting...
๐ง Woodlands-fw2: Firewall is rebooting...
๐ง Woodlands-fw2: Firewall is rebooting...
๐ง Woodlands-fw2: Firewall is rebooting...
๐ง Woodlands-fw2: Firewall is rebooting...
โ
Woodlands-fw2: HA passive firewall rebooted and synchronized with its peer in 483 seconds
โ
panorama.cdot.io: Completed revisiting firewalls
Getting Started
There are two primary methods to utilize the pan-os-upgrade
tool: through a Python virtual environment or via a Docker container. Both methods are outlined below to cater to different preferences or requirements.
Running with Python Virtual Environment
This approach involves setting up a Python virtual environment on your local machine and running the pan-os-upgrade
tool within this isolated environment.
Python Prerequisites
- Python 3.8 or newer.
- Access to a Palo Alto Networks firewall.
- An active internet connection to download the package from PyPI.
Installation
The pan-os-upgrade
library is available on PyPI and can be installed within a Python virtual environment. A virtual environment is a self-contained directory that contains a Python installation for a particular version of Python, plus a number of additional packages.
Creating a Python Virtual Environment
The steps below highlight the process for creating, activating, and installing pan-os-upgrade
into a Python virtual environment. If you're new to Python, it may be beneficial to understand why this is such an important step, here is a good writeup to prime yourself.
-
Create a Virtual Environment:
python3 -m venv panos_env
This command creates a new directory panos_env which contains a copy of the Python interpreter, the standard library, and various supporting files.
-
Activate the Virtual Environment:
On Windows:
panos_env\Scripts\activate
On macOS and Linux:
source panos_env/bin/activate
After activation, your command line will indicate that you are now in the virtual environment.
-
Install
pan-os-upgrade
:Within the activated environment, use pip to install the package:
pip install pan-os-upgrade
Setting Up Your Environment
After setting up the virtual environment and installing the package, you can configure your environment to use the library. This can be done using command-line arguments or using the interactive shell.
Option 1: Execute pan-os-upgrade
without Command-Line Arguments
You can simply get started by issuing pan-os-upgrade
from your current working directory, you will be guided to input the missing requirement arguments through an interactive shell.
$ pan-os-upgrade
Hostname or IP: houston.cdot.io
Username: cdot
Password:
Target PAN-OS version: 10.2.4
Filter string (only applicable for Panorama connections) []:
โ
houston.cdot.io: Connection to firewall established
๐ houston: 007954000123453 192.168.255.211
๐ houston: HA mode: disabled
๐ houston: Current PAN-OS version: 10.2.3-h4
๐ houston: Target PAN-OS version: 10.2.4
โ
houston: Upgrade required from 10.2.3-h4 to 10.2.4
โ
houston: PAN-OS version 10.2.4 is available for download
โ
houston: Base image for 10.2.4 is already downloaded
๐ houston: Performing test to see if 10.2.4 is already downloaded...
๐ houston: PAN-OS version 10.2.4 is not on the firewall
๐ houston: PAN-OS version 10.2.4 is beginning download
Device 007954000123453 downloading version: 10.2.4
๐ง houston: Downloading PAN-OS version 10.2.4 - Elapsed time: 11 seconds
๐ง houston: Downloading PAN-OS version 10.2.4 - Elapsed time: 48 seconds
๐ง houston: Downloading PAN-OS version 10.2.4 - Elapsed time: 84 seconds
โ
houston: 10.2.4 downloaded in 118 seconds
โ
houston: PAN-OS version 10.2.4 has been downloaded.
๐ houston: Performing snapshot of network state information...
โ
houston: Network snapshot created successfully
๐ houston: Performing readiness checks to determine if firewall is ready for upgrade...
โ
houston: Passed Readiness Check: Check if there are pending changes on device
โ
houston: Passed Readiness Check: No Expired Licenses
โ
houston: Passed Readiness Check: Check if NTP is synchronized
โ
houston: Passed Readiness Check: Check connectivity with the Panorama appliance
โ
houston: Readiness Checks completed
๐ houston: Performing backup of configuration to local filesystem...
๐ houston: Not a dry run, continue with upgrade...
๐ houston: Performing upgrade to version 10.2.4...
๐ houston: Attempting upgrade to version 10.2.4 (Attempt 1 of 3)...
Device 007954000123453 installing version: 10.2.4
โ
houston: Upgrade completed successfully
๐ houston: Rebooting the standalone firewall...
๐ houston: Command succeeded with no output
๐ง houston: Firewall is rebooting...
๐ง houston: Firewall is rebooting...
๐ง houston: Firewall is rebooting...
๐ง houston: Firewall is rebooting...
๐ง houston: Firewall is rebooting...
๐ง houston: Firewall is rebooting...
๐ houston: Firewall version: 10.2.4
โ
houston: Firewall rebooted in 516 seconds
As an alternative to targeting firewalls directly, you can target a Panorama appliance to act as the communication proxy. If you'd like to go down this path, make sure that you add an extra CLI option of --filter
and pass a string representation of your filter.
As of version 0.2.5, the available filters are:
filter type | description | example |
---|---|---|
hostname | use the firewall's hostname as selection criteria | --filter "hostname=Woodlands*" |
serial | use the firewall's serial as selection criteria | --filter "serial=007054000123456" |
$ pan-os-upgrade
Hostname or IP: panorama.cdot.io
Username: cdot
Password:
Target PAN-OS version: 10.2.2-h2
Filter string (only applicable for Panorama connections) []: hostname=Woodlands*
โ
panorama.cdot.io: Connection to Panorama established. Firewall connections will be proxied!
๐ Woodlands-fw1: 007954000123451 192.168.255.43
๐ Woodlands-fw2: 007954000123452 192.168.255.44
๐ Woodlands-fw1: HA mode: passive
๐ Woodlands-fw2: HA mode: active
๐ Woodlands-fw2: Detected active firewall in HA pair running the same version as its peer. Added firewall to revisit list.
๐ Woodlands-fw1: Current PAN-OS version: 10.2.2
๐ Woodlands-fw1: Target PAN-OS version: 10.2.2-h2
โ
Woodlands-fw1: Upgrade required from 10.2.2 to 10.2.2-h2
โ
Woodlands-fw1: PAN-OS version 10.2.2-h2 is available for download
โ
Woodlands-fw1: Base image for 10.2.2-h2 is already downloaded
๐ Woodlands-fw1: Performing test to see if 10.2.2-h2 is already downloaded...
๐ Woodlands-fw1: PAN-OS version 10.2.2-h2 is not on the firewall
๐ Woodlands-fw1: PAN-OS version 10.2.2-h2 is beginning download
Device 007954000123451 downloading version: 10.2.2-h2
๐ง Woodlands-fw1: Downloading PAN-OS version 10.2.2-h2 - HA will sync image - Elapsed time: 5 seconds
... shortened for brevity ...
Option 2: Execute pan-os-upgrade
Using Command-Line Arguments
Alternatively, you can pass these details as command-line arguments when running the script:
pan-os-upgrade --hostname 192.168.1.1 --username admin --password secret --version 10.1.0
For a dry run:
pan-os-upgrade --hostname 192.168.1.1 --username admin --password secret --version 10.1.0 --dry-run
If you're targeting a Panorama appliance to act as a proxy for communications to the firewall, make sure you also pass a filter pattern:
pan-os-upgrade --hostname panorama.cdot.io --username admin --password secret --version 10.1.0 --filter "hostname=houston"
Running with Docker
Alternatively, you can run pan-os-upgrade
as a Docker container. This method ensures that the tool runs in an isolated environment with all its dependencies packaged together.
Docker Prerequisites
- Docker installed on your system. You can download it from Docker's official site.
Pulling the Docker Image
First, pull the pan-os-upgrade
image from GitHub Packages:
docker pull ghcr.io/cdot65/pan-os-upgrade:latest
Running the Container
To run the container and mount local directories for assurance
and logs
, use the following commands:
On macOS and Linux:
docker run -v $(pwd)/assurance:/app/assurance -v $(pwd)/logs:/app/logs -it pan-os-upgrade
On Windows:
docker run -v %CD%/assurance:/app/assurance -v %CD%/logs:/app/logs -it pan-os-upgrade
These commands mount the current directory's assurance
and logs
subdirectories to the corresponding directories in the container. If these directories don't exist on your host, Docker will create them.
Interactive Mode
The container will start in interactive mode, prompting you for the necessary input like IP address, username, password, and target PAN-OS version.
Accessing Logs and Output
After the container stops, you can find the logs and other output files in the assurance
and logs
directories of your current working directory on your host machine.
Usage
The script can be run from the command line with various options.
You can view all arguments by passing the --help
flag:
pan-os-upgrade --help
CLI Arguments Description
cli argument | shorthand | type | description |
---|---|---|---|
--dry-run |
-d |
n/a | Perform a dry run of all tests and downloads without performing the actual upgrade. |
--filter |
-f |
conditional | Filter criteria for selecting devices when using Panorama. |
--hostname |
-h |
text | Hostname or IP address of target firewall. |
--log-level |
-l |
text | Set the logging output level (e.g., debug, info, warning). |
--password |
-p |
text | Password for authentication. |
--username |
-u |
text | Username for authentication. |
--version |
-v |
text | Target PAN-OS version to upgrade to. |
Refer to the documentation for more details on usage.
Output
The script generates several files containing the state of the firewall and readiness checks. These files are stored in the assurance
directory with the following structure:
snapshots
: Contains the pre and post-upgrade network state snapshots in JSON format.readiness_checks
: Contains the results of readiness checks in JSON format.configurations
: Contains the backup of the firewall's configuration in XML format.
Logging
Log messages are printed to the console and saved to a rotating log file located in the logs
directory. The log level can be set via the --log-level
argument.
Troubleshooting
Encountered an issue? Here are some common problems and solutions:
-
Problem: Script fails to connect to the PAN-OS device.
- Solution: Check if the hostname and credentials are correct. Ensure network connectivity to the PAN-OS device.
-
Problem: Script hangs during execution.
- Solution: Check the firewall and network settings. Ensure the PAN-OS device is responding correctly.
For more troubleshooting tips, visit our FAQ section.
Contributing
Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.
If you have a suggestion that would make this better, please fork the repo and create a pull request or open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!
- Fork the Project
- Create your Feature Branch (
git checkout -b feature/AmazingFeature
) - Commit your Changes (
git commit -m 'Add some AmazingFeature'
) - Push to the Branch (
git push origin feature/AmazingFeature
) - Open a Pull Request
See Contributing Guidelines for detailed instructions.
License
This project is licensed under the Apache 2.0 License - see the LICENSE file for details.
Contact
Email Address - cremsburg.dev at gmail.com
Project Link: https://github.com/cdot65/pan-os-upgrade
Acknowledgments
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for pan_os_upgrade-0.3.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 419c79c85d23fb45cf723aafeb422557a829987ffaf5d8dbdb9e0611c679a1b9 |
|
MD5 | e7ae735b8da6e51370081a8be291239b |
|
BLAKE2b-256 | a966d4273c839224fffbdecbe7536a5a3cdb2e760e19d45d96ce054adfeb3b9c |