Merge pull request #2 from PaloAltoNetworks/docs-and-readme

Docs and readme

.github/workflows/release.yml

@@ -3,34 +3,30 @@ name: Releases
 on:
   push:
     tags:
-    - '*'
+      - '*'
 
 jobs:
 
   zip_and_release:
-    env:
-      PYTHON_RELEASE_VERSION: 3.10
-      PACK_NAME: PAN_OS_Upgrade_Services
-
     name: "Package ZIP And upload as release."
     runs-on: ubuntu-latest
     permissions:
       contents: write
     steps:
-    - uses: actions/checkout@v3
-    - name: "Set up Python $PYTHON_RELEASE_VERSION"
-      uses: actions/setup-python@v4
-      with:
-        python-version: "$PYTHON_RELEASE_VERSION"
-    - name: Install dependencies
-      run: |
-        python -m pip install --upgrade pip
-        pip install pytest demisto-sdk
-        if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
-    - name: Create content zip
-      run: |
-        demisto-sdk zip-packs -i Packs/$PACK_NAME/ -o /tmp
-    - uses: ncipollo/release-action@v1
-      with:
-        artifacts: "/tmp/uploadable_packs/$PACK_NAME"
-        bodyFile: "release.md"
+      - uses: actions/checkout@v3
+      - name: "Set up Python 3.10"
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.10"
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install pytest demisto-sdk
+          if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
+      - name: Create content zip
+        run: |
+          demisto-sdk zip-packs -i Packs/PAN_OS_Upgrade_Services/ -o /tmp
+      - uses: ncipollo/release-action@v1
+        with:
+          artifacts: "/tmp/uploadable_packs/PAN_OS_Upgrade_Services.zip"
+          bodyFile: "release.md"

Packs/PAN_OS_Upgrade_Services/Integrations/PAN_OS_Device_Management/PAN_OS_Device_Management.yml

@@ -69,4 +69,4 @@ script:
   dockerimage: demisto/pan-os-python:1.0.0.30307
   feed: true
   runonce: false
-  subtype: python3
+  subtype: python3

Packs/PAN_OS_Upgrade_Services/Integrations/PAN_OS_Device_Management/PAN_OS_Device_Management_description.md

@@ -0,0 +1,6 @@
+## PAN-OS Device Management
+This integration ingests PAN-OS NGFW and Panorama devices as indicators into the TIM database using a standard indicator fetch.
+
+You must have a valid [Panorama API key](https://docs.paloaltonetworks.com/pan-os/9-1/pan-os-panorama-api/get-started-with-the-pan-os-xml-api/get-your-api-key) and access to the Panorama server from XSOAR.
+
+This integration **must** be connected to Panorama and does not support direct connection to a PAN-OS NGFW specifically.

Packs/PAN_OS_Upgrade_Services/Integrations/PAN_OS_Upgrade_Assurance/README.md

@@ -0,0 +1,176 @@
+Operational testing for PAN-OS for PAN-OS upgrades.
+This integration was integrated and tested with version xx of PAN_OS_Upgrade_Assurance
+
+## Configure PAN-OS Assurance Testing on Cortex XSOAR
+
+1. Navigate to **Settings** > **Integrations** > **Servers & Services**.
+2. Search for PAN-OS Assurance Testing.
+3. Click **Add instance** to create and configure a new integration instance.
+
+    | **Parameter** | **Required** |
+    | --- | --- |
+    | Panorama IP or Hostname | True |
+    | Panorama Username | True |
+    | Panorama Password | True |
+    | Server Port | False |
+    | Trust any certificate (not secure) | False |
+    | Use system proxy settings | False |
+
+4. Click **Test** to validate the URLs, token, and connection.
+
+## Commands
+
+You can execute these commands from the Cortex XSOAR CLI, as part of an automation, or in a playbook.
+After you successfully execute a command, a DBot message appears in the War Room with the command details.
+
+### pan-os-assurance-run-readiness-checks
+
+***
+Runs checks to confirm a PAN-OS firewall is ready to be upgraded.
+
+#### Base Command
+
+`pan-os-assurance-run-readiness-checks`
+
+#### Input
+
+| **Argument Name** | **Description** | **Required** |
+| --- | --- | --- |
+| firewall_serial | The firewall serial number to run validations against. Use `pan-os-platform-get-system-info if not known`. | Required | 
+| check_list | List of tests to run. If not provided, a base set of tests will be run. | Optional | 
+| min_content_version | The minimum content version to check for, enables "content_version" check. | Optional | 
+| candidate_version | The candidate version to runchecks against. Enables "free_disk_space" check. | Optional | 
+| dp_mp_clock_diff | The drift allowed between DP clock and MP clock. Enabled "planes_clock_sync" check. | Optional | 
+| ipsec_tunnel_status | Check a specific IPsec - by tunnel name. Tunnel must be up for this check to pass. | Optional | 
+| check_session_exists | Check for the presence of a specific connection. Session check format is &lt;source&gt;/destination/destination-port. example: 10.10.10.10/8.8.8.8/443<br/>. | Optional | 
+
+#### Context Output
+
+| **Path** | **Type** | **Description** |
+| --- | --- | --- |
+| FirewallAssurance.ReadinessCheckResults | Unknown | Readiness check results | 
+
+#### Command example
+```!pan-os-assurance-run-readiness-checks firewall_serial=6DF15830EBE327F```
+#### Context Example
+```json
+{
+    "FirewallAssurance": {
+        "Firewall": "6DF15830EBE327F",
+        "ReadinessCheckResults": [
+            {
+                "Test": "panorama",
+                "reason": "[SUCCESS] ",
+                "state": true
+            },
+            {
+                "Test": "ntp_sync",
+                "reason": "[ERROR] No NTP server configured.",
+                "state": false
+            },
+            {
+                "Test": "candidate_config",
+                "reason": "[SUCCESS] ",
+                "state": true
+            },
+            {
+                "Test": "expired_licenses",
+                "reason": "[SUCCESS] ",
+                "state": true
+            },
+            {
+                "Test": "ha",
+                "reason": "[ERROR] Device is not a member of an HA pair.",
+                "state": false
+            }
+        ]
+    }
+}
+```
+
+#### Human Readable Output
+
+>### Readiness Check Results
+>|Test|state|reason|
+>|---|---|---|
+>| panorama | true | [SUCCESS]  |
+>| ntp_sync | false | [ERROR] No NTP server configured. |
+>| candidate_config | true | [SUCCESS]  |
+>| expired_licenses | true | [SUCCESS]  |
+>| ha | false | [ERROR] Device is not a member of an HA pair. |
+
+
+### pan-os-assurance-run-snapshot
+
+***
+Takes a snapshot of the operational state of the system.
+
+#### Base Command
+
+`pan-os-assurance-run-snapshot`
+
+#### Input
+
+| **Argument Name** | **Description** | **Required** |
+| --- | --- | --- |
+| firewall_serial | The firewall serial number to run validations against. Use `pan-os-platform-get-system-info if not known`. | Required | 
+| snapshot_name | The name of the snapshot to take. Defaults to "fw_snapshot". | Optional | 
+| check_list | List of tests to run. If not provided, a base set of tests will be run. | Optional | 
+
+#### Context Output
+
+| **Path** | **Type** | **Description** |
+| --- | --- | --- |
+| File.EntryID | Unknown | The EntryID of the report file. | 
+| File.Extension | String | The extension of the report file. | 
+| File.Name | String | The name of the report file. | 
+| File.Info | String | The info of the report file. | 
+| File.Size | Number | The size of the report file. | 
+| File.Type | String | The type of the report file. | 
+
+#### Command example
+```!pan-os-assurance-run-snapshot firewall_serial=6DF15830EBE327F```
+#### Context Example
+```json
+{
+    "File": {
+        "EntryID": "111@d0971597-2a3e-4375-8c4f-043d162d8a06",
+        "Info": "text/plain",
+        "MD5": "a8a4d8e1c18bf547c4b32ee05f50a59e",
+        "Name": "fw_snapshot",
+        "SHA1": "73b3b749b8f7e30f886a733aa9b7d01ad88254a6",
+        "SHA256": "e4d5b3e8a4d38e3ee5a5a188cbc1d91d54519bef03f87be0ee1f5ccf4ddd9fed",
+        "SHA512": "e8d38c4f54c22b0c0aa2d7b3e77dd6c7334633b15bf95f288f325601eb641eee8f36129e95f670b1998f64251c697afbba977c8316771996fe2456bed82e1b1b",
+        "SSDeep": "96:8fflcsfEIQfjfgifAf58fwGxWUei2BgxC23n1SefKfMfqfRQGQtnCJ/T:+k2i0gxC6n1SerkECt",
+        "Size": 6362,
+        "Type": "ASCII text"
+    }
+}
+```
+
+#### Human Readable Output
+
+
+
+### pan-os-assurance-compare-snapshots
+
+***
+Takes a snapshot of the operational state of the system.
+
+#### Base Command
+
+`pan-os-assurance-compare-snapshots`
+
+#### Input
+
+| **Argument Name** | **Description** | **Required** |
+| --- | --- | --- |
+| left_snapshot_id | The Left (or "first") snapshot to compare. | Required | 
+| right_snapshot_id | The right (or "second") snapshot to compare. | Required | 
+
+#### Context Output
+
+| **Path** | **Type** | **Description** |
+| --- | --- | --- |
+| FirewallAssurance.SnapshotComparisonResult | Unknown | Snapshot comparison results | 
+| FirewallAssurance.SnapshotComparisonRawResult | Unknown | The complete snapshot comparison results | 

Packs/PAN_OS_Upgrade_Services/Integrations/PAN_OS_Upgrade_Assurance/command_examples.txt

@@ -0,0 +1,2 @@
+pan-os-assurance-run-readiness-checks firewall_serial=6DF15830EBE327F
+pan-os-assurance-run-snapshot firewall_serial=6DF15830EBE327F

README.md

@@ -1,9 +1,35 @@
 # XSOAR Upgrade Services 
 
 [![license](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE) [![support](https://img.shields.io/badge/Support%20Level-Community-yellowgreen)](./SUPPORT.md)
+![Test status](https://github.com/PaloAltoNetworks/xsoar-panos-upgrade-automation/actions/workflows/test_and_secrets.yml/badge.svg)
+![Release status](https://github.com/PaloAltoNetworks/xsoar-panos-upgrade-automation/actions/workflows/release.yml/badge.svg)
+
+[Installation guide](docs/installation.md)
 
 ## Description
-WIP - An XSOAR content pack for managing the PAN-OS Upgrade process.
+
+An XSOAR content pack for managing PAN-OS Firewall upgrades at scale.
+
+This pack;
+
+ * Starts, monitors, and tests Firewall upgrades from XSOAR
+ * Allows you to batch upgrades together and run upgrades in parallel 
+ * Calculates upgrade paths and performs intermediary upgrades when moving between major releases
+ * Manages active/passive High Availability 
+ * Tests the upgrades were successful 
+
+## Dependencies
+
+This pack leverages the excellent [pan-os-python](https://github.com/PaloAltoNetworks/pan-os-python) and 
+[pan-os-upgrade-assurance](https://github.com/PaloAltoNetworks/pan-os-upgrade-assurance) libraries to function.
+
+## Demo
+
+[![XSOAR Demo](http://img.youtube.com/vi/uqYXrNPKqkI/0.jpg)](https://www.youtube.com/watch?v=uqYXrNPKqkI "XSOAR Demo Video")
 
 ## License
-This project is licensed under the MIT License - see the [LICENSE](./LICENSE) file for details
+This project is licensed under the MIT License - see the [LICENSE](./LICENSE) file for details
+
+## Support
+
+Support for this project is provided as "best-effort" by Palo Alto Networks. 

docs/installation.md

@@ -0,0 +1,26 @@
+# Installation
+
+## Requirements
+
+ * XSOAR Enterprise + TIM License
+ * Panorama deployed
+ * Network access between Cortex XSOAR and Github Container Registry
+
+## Installing the pack
+
+1. From the [Github releases page](https://github.com/PaloAltoNetworks/xsoar-panos-upgrade-automation/releases), chose the latest release.
+2. Download the Upgrade Services zip file.
+![releases](assets/releases.png)
+3. In your XSOAR server, navigate to settings->about->troubleshooting.
+4. At the bottom of the page, upload the zip file. It can take up to 5 minutes to upload to the server
+![Custom Content](assets/custom_content_upload.png)
+
+## Configuring the integrations
+
+1. Configure the Core Rest API integration.
+2. Configure an instance of the PAN-OS integration - ensuring you're using the Panorama server.
+3. Configure the PAN-OS Device Management integration.
+4. Configure the PAN-OS Assurance Testing integration.
+
+Now you should be done. You'll see your connected firewalls appear under Threat Intel, and be able to launch upgrades
+and assurance testing from there.