Initial Release

.ansible-lint.yml

@@ -0,0 +1,8 @@
+---
+# ansible-lint configuration
+
+profile: basic
+
+skip_list:
+  - key-order
+  - var-naming[non-string]

.github/workflows/ci.yml

@@ -0,0 +1,74 @@
+name: CI
+
+on:
+  pull_request:
+    branches: [ master ]
+
+jobs:
+  ansible-syntax:
+    runs-on: ubuntu-latest
+    name: Ansible Syntax Check
+
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+
+    - name: Set up Python
+      uses: actions/setup-python@v4
+      with:
+        python-version: '3.11'
+
+    - name: Install Ansible
+      run: |
+        python -m pip install --upgrade pip
+        pip install ansible ansible-lint
+
+    - name: Install PAN-OS collection
+      run: |
+        ansible-galaxy collection install paloaltonetworks.panos
+
+    - name: Ansible syntax check
+      run: |
+        find playbooks -name "*.yml" -exec ansible-playbook --syntax-check {} \;
+
+    - name: Ansible lint
+      run: |
+        ansible-lint playbooks/
+
+  python-tests:
+    runs-on: ubuntu-latest
+    name: Python Filter Tests
+
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+
+    - name: Set up Python
+      uses: actions/setup-python@v4
+      with:
+        python-version: '3.11'
+
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install pytest
+
+    - name: Run custom filter tests
+      run: |
+        cd filter_plugins
+        python -m pytest test_custom_filters.py -v
+
+  secrets-scan:
+    runs-on: ubuntu-latest
+    name: Secrets Scanning
+
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+      with:
+        fetch-depth: 0
+
+    - name: Run GitLeaks
+      uses: gitleaks/gitleaks-action@v2
+      env:
+        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/release.yml

@@ -0,0 +1,36 @@
+name: Release
+
+on:
+  push:
+    branches: [ master ]
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    name: Create Release
+
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+      with:
+        fetch-depth: 0
+        token: ${{ secrets.GITHUB_TOKEN }}
+
+    - name: Set up Node.js
+      uses: actions/setup-node@v4
+      with:
+        node-version: '18'
+
+    - name: Install semantic-release
+      run: |
+        npm install -g semantic-release
+        npm install -g @semantic-release/changelog
+        npm install -g @semantic-release/git
+        npm install -g @semantic-release/github
+        npm install -g @semantic-release/commit-analyzer
+        npm install -g @semantic-release/release-notes-generator
+
+    - name: Run semantic-release
+      env:
+        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      run: semantic-release

.gitignore

@@ -0,0 +1,39 @@
+# Test Results Directory
+# Exclude all test results but keep the directory structure
+test_results/runs/
+test_results/latest
+test_results/reports/
+test_results/archives/
+
+# Ansible temporary files
+*.retry
+.ansible/
+
+# Python bytecode
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Environment variables
+.env
+.env.local
+
+# IDE and editor files
+.vscode/
+*.swp
+*.swo
+*~
+
+# OS generated files
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+
+# Logs
+*.log
+inventory_real.yml
+collections

.releaserc.json

@@ -0,0 +1,16 @@
+{
+  "branches": ["master"],
+  "plugins": [
+    "@semantic-release/commit-analyzer",
+    "@semantic-release/release-notes-generator",
+    "@semantic-release/changelog",
+    [
+      "@semantic-release/git",
+      {
+        "assets": ["CHANGELOG.md"],
+        "message": "chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}"
+      }
+    ],
+    "@semantic-release/github"
+  ]
+}

README.md

@@ -0,0 +1,66 @@
+# Ansible PAN-OS Policy Automation
+
+This repository provides a framework and a philosophy for creating PAN-OS security policies
+via Automation.
+
+This repository would be of interest to you if:
+
+ * You deal with a large number of incoming user requests for security policy
+ * You can make repeatable, actionable policy decisions 
+ * You are comfortable with Ansible or General automation platforms.
+
+## Quickstart
+
+### Requirements
+
+ * 🐍 Python 3.11+
+ * Ansible 2.16+
+
+
+### Install the Paloaltonetworks Collection
+
+```shell
+ansible-galaxy install paloaltonetworks.panos
+```
+
+### Clone this repo
+
+```shell
+# ssh
+git clone git@github.com:adambaumeister/ansible_panos_policy_orchestration.git
+# https
+https://github.com/adambaumeister/ansible_panos_policy_orchestration.git
+```
+
+### Define your Inventory
+
+```yaml title='inventory.yml'
+all:
+  children:
+    # the `lab` group is included here as an example, but you can layout your panorama devices however you like.
+    # Note you will need to create your own primary playbook mirroring `lab_policy.yml` if you change the grouping.
+    lab:
+      hosts:
+        lab-panorama01:
+          ansible_host: < YOUR PANORAMA HOSTNAME OR IP HERE >
+          # Password should be provided via PAN_PASSWORD environment variable
+          # Example: export PAN_PASSWORD="admin_password"
+
+          # Username should be provided via PAN_USERNAME environment variable
+          # Example: export PAN_USERNAME="admin"
+      vars:
+        # Common variables for lab environment
+        ansible_connection: local
+        ansible_python_interpreter: "{{ ansible_playbook_python }}"
+        # These variables are only used when creating COMPLETELY NEW policies
+        default_new_policy_device_group: Lab
+        default_new_policy_rulebase: post-rulebase
+        default_new_policy_tag: AUTOMATED
+        default_rule_location: bottom
+```
+
+### Run the connectivity playbook to validate connectivity
+
+```shell
+ansible-playbook playbooks/testing/connectivity.yml
+```

ansible.cfg

@@ -0,0 +1,40 @@
+[defaults]
+# Ansible configuration for Policy as Code lab environment
+
+# Don't forget to set this!
+filter_plugins = ./filter_plugins
+
+# Inventory
+inventory = inventory.yml
+
+# Logging and output
+log_path = test_results/latest/ansible.log
+stdout_callback = yaml
+callback_whitelist = timer, profile_tasks
+
+# Performance and behavior
+gathering = smart
+fact_caching = jsonfile
+fact_caching_connection = test_results/latest/facts
+fact_caching_timeout = 86400
+host_key_checking = False
+retry_files_enabled = True
+retry_files_save_path = test_results/latest/
+
+# Collections and modules
+collections_paths = ./collections
+
+# SSH and connection settings
+timeout = 30
+remote_user = admin
+private_key_file = ~/.ssh/id_rsa
+
+[ssh_connection]
+ssh_args = -o ControlMaster=auto -o ControlPersist=60s -o UserKnownHostsFile=/dev/null
+pipelining = True
+
+[inventory]
+enable_plugins = host_list, script, auto, yaml, ini
+
+[callback_profile_tasks]
+task_output_limit = 20

docs/index.md

@@ -0,0 +1,68 @@
+# Welcome the PAN-OS Policy Orchestration (with Ansible!) docs
+
+This repository provides a framework and a philosophy for creating PAN-OS security policies
+via Automation.
+
+This repository would be of interest to you if:
+
+ * You deal with a large number of incoming user requests for security policy
+ * You can make repeatable, actionable policy decisions 
+ * You are comfortable with Ansible or General automation platforms.
+
+## Quickstart
+
+### Requirements
+
+ * 🐍 Python 3.11+
+ * Ansible 2.16+
+
+
+### Install the Paloaltonetworks Collection
+
+```shell
+ansible-galaxy install paloaltonetworks.panos
+```
+
+### Clone this repo
+
+```shell
+# ssh
+git clone git@github.com:adambaumeister/ansible_panos_policy_orchestration.git
+# https
+https://github.com/adambaumeister/ansible_panos_policy_orchestration.git
+```
+
+### Define your Inventory
+
+```yaml title='inventory.yml'
+all:
+  children:
+    # the `lab` group is included here as an example, but you can layout your panorama devices however you like.
+    # Note you will need to create your own primary playbook mirroring `lab_policy.yml` if you change the grouping.
+    lab:
+      hosts:
+        lab-panorama01:
+          ansible_host: < YOUR PANORAMA HOSTNAME OR IP HERE >
+          # Password should be provided via PAN_PASSWORD environment variable
+          # Example: export PAN_PASSWORD="admin_password"
+
+          # Username should be provided via PAN_USERNAME environment variable
+          # Example: export PAN_USERNAME="admin"
+      vars:
+        # Common variables for lab environment
+        ansible_connection: local
+        ansible_python_interpreter: "{{ ansible_playbook_python }}"
+        # These variables are only used when creating COMPLETELY NEW policies
+        default_new_policy_device_group: Lab
+        default_new_policy_rulebase: post-rulebase
+        default_new_policy_tag: AUTOMATED
+        default_rule_location: bottom
+```
+
+### Run the connectivity playbook to validate connectivity
+
+```shell
+ansible-playbook playbooks/testing/connectivity.yml
+```
+
+[Proceed to the User Guide](user_guide/introduction.md)

docs/user_guide/introduction.md

@@ -0,0 +1,26 @@
+# Ansible PAN-OS Policy Orchestration
+
+This project is designed to help Firewall administrators manage incoming requests for PAN-OS security policy by
+automating as much as the process as possible, in as maintainable a way as possible.
+
+## Non-technical Requirements/Assumptions
+
+The successful implementation of this project assumes some basics about the Firewall operating environment.
+
+ 1. When users/customers request network access, they are able to gather and provide basic technical details
+    1. Source IP/DestinationIP/Application
+ 2. You have some mechanism for triggering this automation.
+    1. Ansible EDA triggered by ITSM webhook
+    2. Github or Gitlab CICD pipeline
+    3. Manual or Cron based execution
+ 3. You are using a typical routed firewall environment (not transparent/switched)
+
+## Other considerations
+
+This automation is based on the idea that all PAN-OS configuration should be obvious to administrators of the devices.
+
+For this reason, we don't use DAG objects, which means changes require commits and the overall process is less efficient
+ but is more applicable to brownfield environments.
+
+If that sounds good, proceed to [Configuring Preset Policy](preset_policy.md)
+