Awesome
panos
Table of Contents
- Module Description - What the module does and why it is useful
- Support
- Setup - The basics of getting started with PANOS
- Usage - Configuration options and additional functionality
- Reference - An under-the-hood peek at what the module is doing and how
- Limitations - OS compatibility, etc.
- Development - Guide for contributing to the module
Module Description
The PANOS module configures Palo Alto firewalls running PANOS 7.1.0 or PANOS 8.1.0.
When committing changes to resources, include panos_commit
in your manifest, or execute the commit
task. You must do this before they can be made available to the running configuration.
The module provides a Puppet task to manually commit
, store_config
to a file, and set_config
from a file.
Support
This module is not supported or maintained by Puppet and does not qualify for Puppet Support plans. It's provided without guarantee or warranty and you can use it at your own risk. All bugfixes, updates, and new feature development will come from community contributions. [tier:community]
Setup
Install the module on either a Puppet server or Puppet agent, by running puppet module install puppetlabs-panos
. To install from source, download the tar file from GitHub and run puppet module install <file_name>.tar.gz --force
.
This module installs the Builder and Puppet Resource API gems, if necessary. To activate the Puppet Resource API gem on the server, reload the puppetserver service. In most cases, this happens automatically and causes little to no interruption to service.
Setup Requirements
Device access
The PANOS module requires access to the device's web management interface.
Proxy Puppet agent
Since a Puppet agent is not available for Palo Alto devices, we need a proxy Puppet agent (either a compile server, or another agent) to run Puppet on behalf of the device.
Install dependencies
Once the module has been installed, install dependencies of the module:
- Classify or apply the
panos
class on each server (server of servers, and if present, compile servers and replica server) that serves catalogs for this module. - Classify or apply the
panos
class on each proxy Puppet agent that proxies for Palo Alto devices.
Run puppet agent -t on the server(s) before using the module on the agent(s).
Getting started with PANOS
To get started, create or edit /etc/puppetlabs/puppet/device.conf
on the proxy Puppet agent, add a section for the device (this will become the device's certname
), specify a type of panos
, and specify a url
to a credentials file.
For example:
[firewall.example.com]
type panos
url file:////etc/puppetlabs/puppet/devices/firewall.example.com.conf
Next, create a credentials file. See the HOCON documentation for information on quoted/unquoted strings and connecting the device.
There are two valid types of credential files that can be placed in /etc/puppetlabs/puppet/devices/firewall.example.com.conf
:
- (a) A file containing the host, username and password in plain text, for example:
host: 10.0.10.20 user: admin password: admin ssl: false
- (b) A file containing the host and an API key obtained from the device, for example:
host: 10.0.10.20 apikey: LUFRPT10cHhRNXMyR2wrYW1MSzg5cldhNElodmVkL1U9OEV1cGY5ZjJyc2xGL1Z4Qk9TNFM2dz09 ssl: false
To obtain an API key for the device, it is possible to use the panos::apikey
task. Before running this task, install the module on your machine, along with Puppet Bolt. When complete, execute the following command:
bolt task run panos::apikey --nodes pan --modulepath <module_installation_dir> --inventoryfile <inventory_yaml_path>
The following inventory file can be used to connect to your firewall.
# inventory.yaml
nodes:
- name: firewall.example.com
alias: pan
config:
transport: remote
remote:
remote-transport: panos
user: admin
password: admin
ssl: false
The --modulepath
param can be retrieved by typing puppet config print modulepath
.
Test your setup and get the certificate signed:
puppet device --verbose --target firewall.example.com
This will sign the certificate and set up the device for Puppet.
For more information, see the puppet device
documentation
To get more practice using PANOS, try out the hands-on labs.
SSL Certificate Verification
To configure SSL certificate verification, add the following ssl
keys to your credentials file:
ssl
: to enable SSL verification. Valid options are false, where no certificate verification happens but HTTPS is still used, or true, where certificate verification occurs. It defaults to true.ssl_ca_file
: the full path to a CA certificate in PEM format. The certificate of the target needs to be signed by this CA. The file needs to exist on the proxy agent's local file system. Only one ofssl_ca_file
andssl_fingerprint
can be provided. Example:'/etc/ssl/certs/Go_Daddy_Root_Certificate_Authority_-_G2.pem'
. Alternatively it will use the certs inOpenSSL::X509::DEFAULT_CERT_FILE
, e.g.:
ruby -ropenssl -e 'puts OpenSSL::X509::DEFAULT_CERT_FILE'
if no ssl.ca_file
is provided
ssl_fingerprint
: a string specifying the SHA256 fingerprint of the firewall's certificate in hex notation. This can be generated byopenssl x509 -sha256 -fingerprint -noout -in cert.pem
or seen in your browser's SSL certificate information. Only one ofssl_ca_file
andssl_fingerprint
can be provided. Example:'9A:6E:C0:12:E1:A7:DA:9D:BE:34:19:4D:47:8A:D7:C0:DB:18:22:FB:07:1D:F1:29:81:49:6E:D1:04:38:41:13'
ssl_ciphers
: array specifying the allowed ciphers for the connection, a list of supported ciphers can be displayed by executingruby -ropenssl -e 'puts OpenSSL::Cipher.ciphers'
, for more details refer to the OpenSSL docs on ciphers.ssl_version
: a string representing the ssl version, e.g.SSLv23
is the default, alternatively the following can be specified:
TLSv1
TLSv1_1
TLSv1_2
For more information refer to the OpenSSL docs.
NOTE: Although not advisable, you can turn off SSL by setting ssl: false
. In doing so you increase the risk of your firewall configuration being hijacked by a potential attacker.
host: 10.0.10.20
username: admin
password: admin
ssl_ciphers: [ECDHE-ECDSA-AES128-GCM-SHA256, ECDHE-RSA-AES128-GCM-SHA256, ECDHE-ECDSA-AES256-GCM-SHA384, ECDHE-RSA-AES256-GCM-SHA384, AES256-GCM-SHA384]
ssl: true
ssl_version: SSLv23
ssl_fingerprint: "EA:21:E5:8F:13:98:73:DB:A6:25:0D:10:1A:08:57:55:34:B4:2C:A8:73:B9:CE:DC:96:4A:74:70:14:A0:7B:6D"
Usage
Now you can manage resources on the Palo Alto device. The module gives you access to various resources on the Palo Alto device, listed in the REFERENCE.md.
The repo's acceptance test examples contain a useful reference on the use of the module's Types.
Note: pw_hash function in the above example requires puppetlabs-stdlib
Puppet Device
To get information from the device, use the puppet device --resource
command. For example, to retrieve addresses on the device, run the following:
puppet device --resource --target firewall.example.com panos_address
To create a new address, write a manifest. Start by making a file named manifest.pp
with the following content:
panos_address { 'somenewaddress':
ensure => 'present',
ip_range => '10.0.0.1-10.0.0.5',
tags => [],
}
Execute the following command:
puppet device --target firewall.example.com --apply manifest.pp
This will apply the manifest. Puppet will check if the address already exists and if it is absent it will create it (idempotency check). When you query for addresses you will see that the new address is available. To do this, run the following command again:
puppet device --resource --target firewall.example.com panos_address
Note that if you get errors, run the above commands with --verbose
- this will give you error message output.
Reference
For full type reference documentation, see the REFERENCE.md
Limitations
This module has only been tested with PANOS 7.1.0 and 8.1.0
Development
Contributions are welcome, especially if they can be of use to other users.
Checkout the repo by forking and creating your feature branch.
Type
Add new types to the type directory. We use the Resource API format.
These PANOS types extend the Resource API by adding in xpath
values, which are used by their respective providers when retireving data from the PANOS API. If the attribute expects multiple values to be returned, it will declare xpath_array
.
Here is a simple example:
require 'puppet/resource_api'
Puppet::ResourceApi.register_type(
name: 'new_thing',
docs: 'Configure the new thing of the device',
features: ['remote_resource'],
base_xpath: 'some/xapth/to/the/type',
attributes: {
ensure: {
type: 'Enum[present, absent]',
desc: 'Whether the new thing should be present or absent on the target system.',
default: 'present',
},
name: {
type: 'String',
desc: 'The name of the new thing',
xpath: 'some/xapth/to/the/type',
behaviour: :namevar,
},
# Other fields in resource API format
},
)
Provider
Add a provider — see existing examples. Parsing logic is contained in each types respective provider directory with a common base provider available.
Testing
There are two levels of testing found under spec
.
To test this module you will need to have a Palo Alto machine available. The virtual machine images from their support area work fine in VirtualBox and VMware. Alternatively you can use the PAYG offering on AWS. Note that the VMs do not need to have license deployed that is usable for development.
Unit Testing
Unit tests test the parsing and command generation logic, executed locally.
First execute bundle exec rake spec_prep
to ensure that the local types are made available to the spec tests. Then execute with bundle exec rake spec
.
Acceptance Testing
Acceptance tests are executed on actual devices.
Use test values and make sure that these are non-destructive.
The acceptance tests locate the Palo Alto box that is used for testing through environment variables. The current test setup allows for three different scenarios:
- Static configuration: the VM or physical box is already running somewhere.
Set
PANOS_TEST_HOST
to the FQDN/IP of the box andPANOS_TEST_PLATFORM
to a platform string in the form ofpalo-alto-VERSION-x86_64
. - VMPooler: if you have a VMPooler instance available, set
VMPOOLER_HOST
to the hostname of your VMPooler instance (it defaults to Puppet's internal service), andPANOS_TEST_PLATFORM
to the platform string of VMPooler you want to use. - ABS: when running on Puppet's internal infrastructure, it passes reserved instances into the job through
ABS_RESOURCE_HOSTS
.
To specify the username and password used to connect to the box, set PANOS_TEST_USER
and PANOS_TEST_PASSWORD
respectively. Palo Alto's VMs default to admin
/admin
, which is also used as a default, if you don't specify anything.
After you have configured the system under test, you can run the acceptance tests directly using:
bundle exec rspec spec/acceptance
or using the legacy rake task
bundle exec rake beaker
Cutting a release
To cut a new release, from a current main
checkout:
- Start the release branch with
git checkout -b release-prep
- Execute the Puppet Strings rake task to update the REFERENCE.md:
bundle exec rake 'strings:generate[,,,,,REFERENCE.md,true]'
- Make sure that all PRs are tagged appropriately