Skip to content

Commit

Permalink
Merge pull request #24 from cdot65:23-update-documentation-for-github…
Browse files Browse the repository at this point in the history 
…-repository-and-pypi-package-deployment

Update documentation and dependencies
  • Loading branch information
@cdot65
cdot65 authored Jan 19, 2024
2 parents 66822d1 + c88705b commit 7bed4d3
Show file tree
Hide file tree
Showing 5 changed files with 1,266 additions and 360 deletions.
6 changes: 3 additions & 3 deletions .gitignore
View file
Original file line number Diff line number Diff line change
Expand Up @@ -162,6 +162,6 @@ cython_debug/
# ignore .env file
.env

# ignore my personal snapshots
pan_os_upgrade/assurance
pan_os_upgrade/logs
# ignore local dev
assurance
logs
187 changes: 100 additions & 87 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,10 +10,10 @@
<!-- PROJECT LOGO -->
<br />
<div align="center">
<img src="images/logo.svg" alt="Logo">
<img src="https://github.com/cdot65/pan-os-upgrade/blob/main/images/logo.svg?raw=true" alt="Logo">
<h3 align="center">PAN-OS Automation Project</h3>
<p align="center">
Automating PAN-OS upgrades using Python
Streamlining Palo Alto Networks Firewall Upgrades with Python Automation
<br />
<a href="https://github.com/cdot65/pan-os-upgrade"><strong>Explore the docs »</strong></a>
<br />
Expand All @@ -23,36 +23,24 @@
<a href="https://github.com/cdot65/pan-os-upgrade/issues">Request Feature</a>
</p>
</div>

<!-- TABLE OF CONTENTS -->
<details>
<summary>Table of Contents</summary>
<ol>
<li>
<a href="#about-the-project">About The Project</a>
<ul>
<li><a href="#built-with">Built With</a></li>
</ul>
</li>
<li>
<a href="#getting-started">Getting Started</a>
<ul>
<li><a href="#prerequisites">Prerequisites</a></li>
<li><a href="#installation">Installation</a></li>
</ul>
</li>
<li><a href="#about-the-project">About The Project</a></li>
<li><a href="#getting-started">Getting Started</a></li>
<li><a href="#usage">Usage</a></li>
<li><a href="#output">Output</a></li>
<li><a href="#logging">Logging</a></li>
<li><a href="#contributing">Contributing</a></li>
<li><a href="#license">License</a></li>
<li><a href="#contact">Contact</a></li>
<li><a href="#acknowledgments">Acknowledgments</a></li>
</ol>
</details>

<!-- ABOUT THE PROJECT -->
## About The Project

[![Project Screenshot][product-screenshot]](https://paloaltonetworks.com)
## 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.

Expand All @@ -64,130 +52,157 @@ Key Features:

> Note: this script is targeted towards standalone and `active-passive` HA environments, no testing has been performed against `active-active` or clustered firewalls.
<p align="right">(<a href="#readme-top">back to top</a>)</p>

### Built With
Example Screenshot

This project is built with the following technologies:

* [Python](https://python.org/)
* [pan-os-python SDK](https://github.com/PaloAltoNetworks/pan-os-python)
* [panos-upgrade-assurance](https://github.com/PaloAltoNetworks/pan-os-upgrade-assurance)
* [Pydantic](https://docs.pydantic.dev/latest/)
* [xmltodict](https://pypi.org/project/xmltodict/)
![Example Screenshot](https://github.com/cdot65/pan-os-upgrade/blob/main/images/screenshot.jpg?raw=true)

<p align="right">(<a href="#readme-top">back to top</a>)</p>

<!-- GETTING STARTED -->
## Getting Started

## Prerequisites
This guide will help you set up the `pan-os-upgrade` library in your environment, especially focusing on users who are new to Python and virtual environments.

* Python 3.x
### Prerequisites

* Python 3.8 or newer.
* Access to a Palo Alto Networks firewall.
* Required Python packages: (found in [requirements.txt](https://github.com/cdot65/pan-os-upgrade/blob/main/requirements.txt) file).
* An active internet connection to download the package from PyPI.

## Getting Started
### Installation

To get started with the PAN-OS upgrade project, you need to set up your environment and install the necessary dependencies.
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.

### Installation
#### Using `python3 -m venv` (Recommended for Beginners)

Clone the repository
1. Create a Virtual Environment:

```bash
git clone https://github.com/cdot65/pan-os-upgrade.git
cd pan-os-upgrade
```
```bash
python3 -m venv panos_env
```

Before running the script, ensure you have Python installed on your system. If you're new to Python, here's how you can set up a virtual environment, which allows us to install Python packages without having them conflict with our system's Python environment:
This command creates a new directory panos_env which contains a copy of the Python interpreter, the standard library, and various supporting files.

* Setting up a virtual environment
2. Activate the Virtual Environment:

If you have Poetry on your machine, simply type `poetry install` and `poetry shell` to activate this project's virtual environment.
On Windows:

If Poetry is not installed, then you can build and activate the Python virtual enviornment manually.
```bash
panos_env\Scripts\activate
```

```bash
python3 -m venv venv
```
On macOS and Linux:

```bash
source venv/bin/activate # On Windows use `venv\Scripts\activate`
```
```bash
source panos_env/bin/activate
```

Once the virutal environment has been created and activated, install the required packages
After activation, your command line will indicate that you are now in the virtual environment.

```bash
pip install -r requirements.txt
```
3. Install `pan-os-upgrade`:

<p align="right">(<a href="#readme-top">back to top</a>)</p>
Within the activated environment, use pip to install the package:

<!-- USAGE EXAMPLES -->
## Usage
```bash
pip install pan-os-upgrade
```

The script can be run from the command line with various options. It requires at least the hostname (or IP address) and the target PAN-OS version for the firewall. Authentication can be done via API key or username and password.
### Using Poetry (Advanced Users)

### CLI Arguments Description
Poetry is a tool for dependency management and packaging in Python. It allows you to declare the libraries your project depends on and it will manage (install/update) them for you.

* `--api-key`: API Key for authentication
* `--dry-run`: Perform a dry run of all tests and downloads without performing the actual upgrade.
* `--hostname`: Hostname or IP address of the PAN-OS firewall.
* `--log-level`: Set the logging output level (e.g., debug, info, warning).
* `--password`: Password for authentication.
* `--username`: Username for authentication.
* `--version`: Target PAN-OS version to upgrade to.
1. Install Poetry:

Follow [the official instructions](https://python-poetry.org/docs/) to install Poetry on your system.

2. Create a New Project using Poetry:

```bash
poetry new panos_project
cd panos_project
```

3. Add `pan-os-upgrade` as a Dependency:

```bash
poetry add pan-os-upgrade
```

This command will create a virtual environment and install the `pan-os-upgrade` package along with its dependencies.

### Define Variables Within .env
4. Activate the Poetry Shell:

As an alternative to passing CLI arguments, which can be a security risk due to your console's history function, you can instead update the variables within the `.env` file of your project.
To activate the virtual environment created by Poetry, use:

These environment variables will be used when CLI arguments are not provided, feel free to mix and match CLI arguments and hardcoded values within the .env file. Just note that if you're using an API key for authentication, leave the username and password blank.
```bash
poetry shell
```

> note: CLI arguments will take precedent of .env file
### 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 an .env file.

#### Option 1: Using an .env File

Create a `.env` file in your local directory and fill it with your firewall's details:
```env
# PAN-OS credientials if using an API key, leave username and password blank
# PAN-OS credentials - use either API key or username/password combination
PAN_USERNAME=admin
PAN_PASSWORD=paloalto123
API_KEY=
# hostname or IP address
# Hostname or IP address of the firewall
HOSTNAME=firewall1.example.com
# target PAN-OS version
# Target PAN-OS version for the upgrade
TARGET_VERSION=11.0.2-h3
# manage the levels of logging of the script debug, info, warning, error, critical
# Logging level (e.g., debug, info, warning, error, critical)
LOG_LEVEL=debug
# dry run will not perform the actual upgrade process
DRY_RUN=
# Set to true for a dry run
DRY_RUN=false
```
#### Option 2: Using Command-Line Arguments
Alternatively, you can pass these details as command-line arguments when running the script:
```bash
pan-os-upgrade --hostname 192.168.1.1 --username admin --password secret --version 10.1.0
```
Then execute your script as follows:
For a dry run:
```bash
python upgrade.py
pan-os-upgrade --hostname 192.168.1.1 --username admin --password secret --version 10.1.0 --dry-run
```
### Dry Run
<p align="right">(<a href="#readme-top">back to top</a>)</p>
To execute a dry run (which performs checks without upgrading):
<!-- USAGE EXAMPLES -->
## Usage
```bash
python upgrade.py --hostname 192.168.1.1 --username admin --password secret --version 10.0.0 --dry-run
```
The script can be run from the command line with various options. It requires at least the hostname (or IP address) and the target PAN-OS version for the firewall. Authentication can be done via API key or username and password.
For more details on the usage and examples, refer to the [documentation](https://cdot65.github.io/pan-os-upgrade/).
### CLI Arguments Description
* `--api-key`: API Key for authentication
* `--dry-run`: Perform a dry run of all tests and downloads without performing the actual upgrade.
* `--hostname`: Hostname or IP address of the PAN-OS firewall.
* `--log-level`: Set the logging output level (e.g., debug, info, warning).
* `--password`: Password for authentication.
* `--username`: Username for authentication.
* `--version`: Target PAN-OS version to upgrade to.
<p align="right">(<a href="#readme-top">back to top</a>)</p>
Refer to the [documentation](https://github.com/cdot65/pan-os-upgrade) for more details on usage.
<p align="right">(<a href="#readme-top">back to top</a>)</p>
<!-- OUTPUT -->
## 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:
Expand All @@ -196,6 +211,7 @@ The script generates several files containing the state of the firewall and read
* `readiness_checks`: Contains the results of readiness checks in JSON format.
* `configurations`: Contains the backup of the firewall's configuration in XML format.

<!-- LOGGING -->
## 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.
Expand All @@ -208,9 +224,6 @@ 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**: Error regarding missing dependencies.
* **Solution**: Ensure all required packages are installed using `pip install -r requirements.txt`.

* **Problem**: Script hangs during execution.
* **Solution**: Check the firewall and network settings. Ensure the PAN-OS device is responding correctly.

Expand Down
Loading

0 comments on commit 7bed4d3

Please sign in to comment.