From 6f7c18d85922612a91bd910fbc312a9ee8a00390 Mon Sep 17 00:00:00 2001 From: Matt Vitale Date: Mon, 15 Nov 2021 07:49:29 -0500 Subject: [PATCH 1/5] Update docs --- README.md | 42 ++++++++++++++-------------- docs/index.md | 76 +++++++++++++++++++++++++++++++++++++++++++++------ 2 files changed, 90 insertions(+), 28 deletions(-) diff --git a/README.md b/README.md index 13fb644..085ecf1 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,22 @@ -# Nautobot Plugin Chatops Panorama +# Nautobot Plugin ChatOps Panorama -A plugin for [Nautobot](https://github.com/nautobot/nautobot). +This is a plugin for [Nautobot](https://github.com/nautobot/nautobot) that extends ChatOps support to the Palo Alto Panorama system. It adds some useful commands into your ChatOps environment that enhance an administrator's and end user's day to day using of Panorama. This framework allows the writing of new ChatOps commands for Panorama very easily. + +Note: While this plugin requires Nautobot and the base Nautobot ChatOps plugin, it does _not_ require the Panorama or Palo Alto inventory to be in Nautobot. It is effectively Nautobot-independent, except for using it as a backend to run the chat bot itself. + +## Usage + +The supported commands are listed below. We welcome any new command or feature requests by submitting an issue or PR. + +| /panorama Command | Description | +| -------------------- | -------------------------------------------------------------------------- | +| capture-traffic | Run a packet capture on PANOS Device for specified IP traffic. | +| export-device-rules | Generate a downloadable list of firewall rules with details in CSV format. | +| get-device-rules | Return a list of all firewall rules on a given device with details. | +| get-version | Obtain software version information for Panorama. | +| install-software | Install software to specified Palo Alto device. | +| upload-software | Upload software to specified Palo Alto device. | +| validate-rule-exists | Verify that a specific ACL rule exists within a device, via Panorama. | ## Prerequisites @@ -33,28 +49,14 @@ PLUGINS = ["nautobot_chatops", "nautobot_plugin_chatops_panorama"] You will need to set the following environment variables for your Nautobot instance, then restart the services for them to take effect. -* PANORAMA_HOST - This is the management DNS/IP address used to reach your Panorama instance. -* PANORAMA_USER - A user account with API access to Panorama. -* PANORAMA_PASSWORD - The password that goes with the above user account. +- PANORAMA_HOST - This is the management DNS/IP address used to reach your Panorama instance. +- PANORAMA_USER - A user account with API access to Panorama. +- PANORAMA_PASSWORD - The password that goes with the above user account. ## Access Control Just like with the regular `/nautobot` command from the base Nautobot ChatOps plugin, the `/panorama` command supports access control through the Access Grants menu in Nautobot. See section [Grant Access to the Chatbot](https://github.com/nautobot/nautobot-plugin-chatops/blob/develop/docs/chat_setup/chat_setup.md#grant-access-to-the-chatbot) in the installation guide for the base Nautobot ChatOps plugin for setting this up. -## Usage - -The supported commands are listed below. We welcome any new command or feature requests by submitting an issue or PR. - -| /panorama Command | Description | -| --------------------- | ------------------------------------- | -| capture-traffic | Run a packet capture on PANOS Device for specified IP traffic. | -| export-device-rules | Generate a downloadable list of firewall rules with details in CSV format. | -| get-device-rules | Return a list of all firewall rules on a given device with details. | -| get-version | Obtain software version information for Panorama. | -| install-software | Install software to specified Palo Alto device. | -| upload-software | Upload software to specified Palo Alto device. | -| validate-rule-exists | Verify that a specific ACL rule exists within a device, via Panorama. | - ## Questions For any questions or comments, please check the [FAQ](FAQ.md) first and feel free to swing by the [Network to Code slack channel](https://networktocode.slack.com/) (channel #networktocode). @@ -72,4 +74,4 @@ Sign up [here](http://slack.networktocode.com/) ![Capture Traffic Filter](docs/img/screenshot5.png) -![Capture Traffic](docs/img/screenshot6.png) \ No newline at end of file +![Capture Traffic](docs/img/screenshot6.png) diff --git a/docs/index.md b/docs/index.md index f7a2c0e..085ecf1 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,17 +1,77 @@ -# NautobotPluginChatopsPanorama +# Nautobot Plugin ChatOps Panorama -TODO: Write plugin documentation, the outline here is provided as a guide and should be expanded upon. If more detail is required you are encouraged to expand on the table of contents (TOC) in `mkdocs.yml` to add additional pages. +This is a plugin for [Nautobot](https://github.com/nautobot/nautobot) that extends ChatOps support to the Palo Alto Panorama system. It adds some useful commands into your ChatOps environment that enhance an administrator's and end user's day to day using of Panorama. This framework allows the writing of new ChatOps commands for Panorama very easily. -## Description +Note: While this plugin requires Nautobot and the base Nautobot ChatOps plugin, it does _not_ require the Panorama or Palo Alto inventory to be in Nautobot. It is effectively Nautobot-independent, except for using it as a backend to run the chat bot itself. + +## Usage + +The supported commands are listed below. We welcome any new command or feature requests by submitting an issue or PR. + +| /panorama Command | Description | +| -------------------- | -------------------------------------------------------------------------- | +| capture-traffic | Run a packet capture on PANOS Device for specified IP traffic. | +| export-device-rules | Generate a downloadable list of firewall rules with details in CSV format. | +| get-device-rules | Return a list of all firewall rules on a given device with details. | +| get-version | Obtain software version information for Panorama. | +| install-software | Install software to specified Palo Alto device. | +| upload-software | Upload software to specified Palo Alto device. | +| validate-rule-exists | Verify that a specific ACL rule exists within a device, via Panorama. | + +## Prerequisites + +This plugin requires the [Nautobot ChatOps Plugin](https://github.com/nautobot/nautobot-plugin-chatops) to be installed and configured before using. You can find detailed setup and configuration instructions [here](https://github.com/nautobot/nautobot-plugin-chatops/blob/develop/README.md). ## Installation -## Configuration +The plugin is available as a Python package in pypi and can be installed with pip: -## Usage +```shell +pip install nautobot-plugin-chatops-panorama +``` + +> The plugin is compatible with Nautobot 1.1.0 and higher + +To ensure Nautobot Plugin ChatOps Panorama is automatically re-installed during future upgrades, create a file named `local_requirements.txt` (if not already existing) in the Nautobot root directory (alongside `requirements.txt`) and list the `nautobot-plugin-chatops-panorama` package: + +```no-highlight +# echo nautobot-plugin-chatops-panorama >> local_requirements.txt +``` + +Once installed, the plugin needs to be enabled in your `nautobot_config.py` + +```python +# In your configuration.py +PLUGINS = ["nautobot_chatops", "nautobot_plugin_chatops_panorama"] +``` + +### Environment Variables + +You will need to set the following environment variables for your Nautobot instance, then restart the services for them to take effect. + +- PANORAMA_HOST - This is the management DNS/IP address used to reach your Panorama instance. +- PANORAMA_USER - A user account with API access to Panorama. +- PANORAMA_PASSWORD - The password that goes with the above user account. + +## Access Control + +Just like with the regular `/nautobot` command from the base Nautobot ChatOps plugin, the `/panorama` command supports access control through the Access Grants menu in Nautobot. See section [Grant Access to the Chatbot](https://github.com/nautobot/nautobot-plugin-chatops/blob/develop/docs/chat_setup/chat_setup.md#grant-access-to-the-chatbot) in the installation guide for the base Nautobot ChatOps plugin for setting this up. + +## Questions + +For any questions or comments, please check the [FAQ](FAQ.md) first and feel free to swing by the [Network to Code slack channel](https://networktocode.slack.com/) (channel #networktocode). +Sign up [here](http://slack.networktocode.com/) + +## Screenshots + +![Help](docs/img/screenshot1.png) + +![Validate Rule Exists Success](docs/img/screenshot2.png) + +![Validate Rule Exists Failure](docs/img/screenshot3.png) -## API +![Upload Software](docs/img/screenshot4.png) -## Views +![Capture Traffic Filter](docs/img/screenshot5.png) -## Models +![Capture Traffic](docs/img/screenshot6.png) From d4867b20b8dc83162cf368cfbee20cbb2d86fc93 Mon Sep 17 00:00:00 2001 From: matt852 Date: Mon, 15 Nov 2021 09:35:46 -0500 Subject: [PATCH 2/5] Update README.md Co-authored-by: Ken Celenza --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 085ecf1..6dfd074 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Nautobot Plugin ChatOps Panorama -This is a plugin for [Nautobot](https://github.com/nautobot/nautobot) that extends ChatOps support to the Palo Alto Panorama system. It adds some useful commands into your ChatOps environment that enhance an administrator's and end user's day to day using of Panorama. This framework allows the writing of new ChatOps commands for Panorama very easily. +This is a plugin for [Nautobot](https://github.com/nautobot/nautobot) that extends ChatOps support to Palo Alto Panorama systems. The plugin adds some useful commands into your ChatOps environment that enhance an administrator's and end user's day to day using of Panorama. This framework allows for the quick extension of new ChatOps commands for Panorama. Note: While this plugin requires Nautobot and the base Nautobot ChatOps plugin, it does _not_ require the Panorama or Palo Alto inventory to be in Nautobot. It is effectively Nautobot-independent, except for using it as a backend to run the chat bot itself. From 6ed06a9b5c580831925f00037810fdcae897ac21 Mon Sep 17 00:00:00 2001 From: Matt Vitale Date: Mon, 15 Nov 2021 09:37:04 -0500 Subject: [PATCH 3/5] Update with PR feedback --- docs/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/index.md b/docs/index.md index 085ecf1..6dfd074 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,6 +1,6 @@ # Nautobot Plugin ChatOps Panorama -This is a plugin for [Nautobot](https://github.com/nautobot/nautobot) that extends ChatOps support to the Palo Alto Panorama system. It adds some useful commands into your ChatOps environment that enhance an administrator's and end user's day to day using of Panorama. This framework allows the writing of new ChatOps commands for Panorama very easily. +This is a plugin for [Nautobot](https://github.com/nautobot/nautobot) that extends ChatOps support to Palo Alto Panorama systems. The plugin adds some useful commands into your ChatOps environment that enhance an administrator's and end user's day to day using of Panorama. This framework allows for the quick extension of new ChatOps commands for Panorama. Note: While this plugin requires Nautobot and the base Nautobot ChatOps plugin, it does _not_ require the Panorama or Palo Alto inventory to be in Nautobot. It is effectively Nautobot-independent, except for using it as a backend to run the chat bot itself. From f4b133e4671ccbe8cb8c3c27a68d309b4499b678 Mon Sep 17 00:00:00 2001 From: Matt Vitale Date: Thu, 18 Nov 2021 13:37:55 -0500 Subject: [PATCH 4/5] Update docs with additional env variable details --- README.md | 65 +++++++++++++++++++++++++++++++++++++++++++++++++++ docs/index.md | 65 +++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 130 insertions(+) diff --git a/README.md b/README.md index 6dfd074..7652090 100644 --- a/README.md +++ b/README.md @@ -45,6 +45,40 @@ Once installed, the plugin needs to be enabled in your `nautobot_config.py` PLUGINS = ["nautobot_chatops", "nautobot_plugin_chatops_panorama"] ``` +In addition, add/update the below `PLUGINS_CONFIG` section to `nautobot_config.py`. + +> It is only necessary to add the sections from the below snippet for the chat platform you will be using (Slack, Webex, etc.). + +```python +# Also in nautobot_config.py +PLUGINS_CONFIG = { + "nautobot_chatops": { + # Slack + "enable_slack": os.environ.get("ENABLE_SLACK", False), + "slack_api_token": os.environ.get("SLACK_API_TOKEN"), + "slack_signing_secret": os.environ.get("SLACK_SIGNING_SECRET"), + "slack_slash_command_prefix": os.environ.get("SLACK_SLASH_COMMAND_PREFIX", "/"), + # Webex + "enable_webex": os.environ.get("ENABLE_WEBEX", False), + "webex_token": os.environ.get("WEBEX_TOKEN"), + "webex_signing_secret": os.environ.get("WEBEX_SIGNING_SECRET"), + # Mattermost + "enable_mattermost": os.environ.get("ENABLE_MATTERMOST", False), + "mattermost_api_token": os.environ.get("MATTERMOST_API_TOKEN"), + "mattermost_url": os.environ.get("MATTERMOST_URL"), + # MS Teams + "enable_ms_teams": os.environ.get("ENABLE_MS_TEAMS", False), + "microsoft_app_id": os.environ.get("MICROSOFT_APP_ID"), + "microsoft_app_password": os.environ.get("MICROSOFT_APP_PASSWORD"), + }, + "nautobot_plugin_chatops_panorama": { + "panorama_host": os.environ.get("PANORAMA_HOST"), + "panorama_user": os.environ.get("PANORAMA_USER"), + "panorama_password": os.environ.get("PANORAMA_PASSWORD"), + }, +} +``` + ### Environment Variables You will need to set the following environment variables for your Nautobot instance, then restart the services for them to take effect. @@ -53,6 +87,37 @@ You will need to set the following environment variables for your Nautobot insta - PANORAMA_USER - A user account with API access to Panorama. - PANORAMA_PASSWORD - The password that goes with the above user account. +```bash +export PANORAMA_HOST="{{ Panorama DNS/URL }}" +export PANORAMA_USER="{{ Panorama account username }}" +export PANORAMA_PASSWORD="{{ Panorama account password }}" +``` + +If the base Nautobot Chatops plugin is not already installed, the following environment variables are required for the chat platform in use. The [Platform-specific Setup](https://github.com/nautobot/nautobot-plugin-chatops/blob/develop/docs/chat_setup/chat_setup.md#platform-specific-setup) document describes how to retrieve the tokens and secrets for each chat platform that will need to be used in the environment variables. + +> It is only necessary to create the environment variables shown below for the chat platform you will be using. To make the environment variables persistent, add them to the ~/.bash_profile for the user running Nautobot. + +```bash +# Slack +export ENABLE_SLACK="true" +export SLACK_API_TOKEN="foobar" +export SLACK_SIGNING_SECRET="foobar" +# Webex +export ENABLE_WEBEX="true" +export WEBEX_TOKEN="foobar" +export WEBEX_SIGNING_SECRET="foobar" +# Mattermost +export ENABLE_MATTERMOST="false" +export MATTERMOST_API_TOKEN="foobar" +export MATTERMOST_URL="foobar" +# Microsoft Teams +export ENABLE_MS_TEAMS="false" +export MICROSOFT_APP_ID="foobar" +export MICROSOFT_APP_PASSWORD="foobar" +``` + +> When deploying as Docker containers, all of the above environment variables should be defined in the file `development/creds.env`. An example credentials file `creds.env.example` is available in the `development` folder. + ## Access Control Just like with the regular `/nautobot` command from the base Nautobot ChatOps plugin, the `/panorama` command supports access control through the Access Grants menu in Nautobot. See section [Grant Access to the Chatbot](https://github.com/nautobot/nautobot-plugin-chatops/blob/develop/docs/chat_setup/chat_setup.md#grant-access-to-the-chatbot) in the installation guide for the base Nautobot ChatOps plugin for setting this up. diff --git a/docs/index.md b/docs/index.md index 6dfd074..7652090 100644 --- a/docs/index.md +++ b/docs/index.md @@ -45,6 +45,40 @@ Once installed, the plugin needs to be enabled in your `nautobot_config.py` PLUGINS = ["nautobot_chatops", "nautobot_plugin_chatops_panorama"] ``` +In addition, add/update the below `PLUGINS_CONFIG` section to `nautobot_config.py`. + +> It is only necessary to add the sections from the below snippet for the chat platform you will be using (Slack, Webex, etc.). + +```python +# Also in nautobot_config.py +PLUGINS_CONFIG = { + "nautobot_chatops": { + # Slack + "enable_slack": os.environ.get("ENABLE_SLACK", False), + "slack_api_token": os.environ.get("SLACK_API_TOKEN"), + "slack_signing_secret": os.environ.get("SLACK_SIGNING_SECRET"), + "slack_slash_command_prefix": os.environ.get("SLACK_SLASH_COMMAND_PREFIX", "/"), + # Webex + "enable_webex": os.environ.get("ENABLE_WEBEX", False), + "webex_token": os.environ.get("WEBEX_TOKEN"), + "webex_signing_secret": os.environ.get("WEBEX_SIGNING_SECRET"), + # Mattermost + "enable_mattermost": os.environ.get("ENABLE_MATTERMOST", False), + "mattermost_api_token": os.environ.get("MATTERMOST_API_TOKEN"), + "mattermost_url": os.environ.get("MATTERMOST_URL"), + # MS Teams + "enable_ms_teams": os.environ.get("ENABLE_MS_TEAMS", False), + "microsoft_app_id": os.environ.get("MICROSOFT_APP_ID"), + "microsoft_app_password": os.environ.get("MICROSOFT_APP_PASSWORD"), + }, + "nautobot_plugin_chatops_panorama": { + "panorama_host": os.environ.get("PANORAMA_HOST"), + "panorama_user": os.environ.get("PANORAMA_USER"), + "panorama_password": os.environ.get("PANORAMA_PASSWORD"), + }, +} +``` + ### Environment Variables You will need to set the following environment variables for your Nautobot instance, then restart the services for them to take effect. @@ -53,6 +87,37 @@ You will need to set the following environment variables for your Nautobot insta - PANORAMA_USER - A user account with API access to Panorama. - PANORAMA_PASSWORD - The password that goes with the above user account. +```bash +export PANORAMA_HOST="{{ Panorama DNS/URL }}" +export PANORAMA_USER="{{ Panorama account username }}" +export PANORAMA_PASSWORD="{{ Panorama account password }}" +``` + +If the base Nautobot Chatops plugin is not already installed, the following environment variables are required for the chat platform in use. The [Platform-specific Setup](https://github.com/nautobot/nautobot-plugin-chatops/blob/develop/docs/chat_setup/chat_setup.md#platform-specific-setup) document describes how to retrieve the tokens and secrets for each chat platform that will need to be used in the environment variables. + +> It is only necessary to create the environment variables shown below for the chat platform you will be using. To make the environment variables persistent, add them to the ~/.bash_profile for the user running Nautobot. + +```bash +# Slack +export ENABLE_SLACK="true" +export SLACK_API_TOKEN="foobar" +export SLACK_SIGNING_SECRET="foobar" +# Webex +export ENABLE_WEBEX="true" +export WEBEX_TOKEN="foobar" +export WEBEX_SIGNING_SECRET="foobar" +# Mattermost +export ENABLE_MATTERMOST="false" +export MATTERMOST_API_TOKEN="foobar" +export MATTERMOST_URL="foobar" +# Microsoft Teams +export ENABLE_MS_TEAMS="false" +export MICROSOFT_APP_ID="foobar" +export MICROSOFT_APP_PASSWORD="foobar" +``` + +> When deploying as Docker containers, all of the above environment variables should be defined in the file `development/creds.env`. An example credentials file `creds.env.example` is available in the `development` folder. + ## Access Control Just like with the regular `/nautobot` command from the base Nautobot ChatOps plugin, the `/panorama` command supports access control through the Access Grants menu in Nautobot. See section [Grant Access to the Chatbot](https://github.com/nautobot/nautobot-plugin-chatops/blob/develop/docs/chat_setup/chat_setup.md#grant-access-to-the-chatbot) in the installation guide for the base Nautobot ChatOps plugin for setting this up. From 4e792f2a7f832419e2b33e8325e0d0293f5233d6 Mon Sep 17 00:00:00 2001 From: Matt Vitale Date: Thu, 18 Nov 2021 18:46:23 -0500 Subject: [PATCH 5/5] Update plugin name as per PR feedback --- README.md | 4 ++-- docs/index.md | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 7652090..0f05684 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# Nautobot Plugin ChatOps Panorama +# Nautobot Panorama ChatOps This is a plugin for [Nautobot](https://github.com/nautobot/nautobot) that extends ChatOps support to Palo Alto Panorama systems. The plugin adds some useful commands into your ChatOps environment that enhance an administrator's and end user's day to day using of Panorama. This framework allows for the quick extension of new ChatOps commands for Panorama. @@ -32,7 +32,7 @@ pip install nautobot-plugin-chatops-panorama > The plugin is compatible with Nautobot 1.1.0 and higher -To ensure Nautobot Plugin ChatOps Panorama is automatically re-installed during future upgrades, create a file named `local_requirements.txt` (if not already existing) in the Nautobot root directory (alongside `requirements.txt`) and list the `nautobot-plugin-chatops-panorama` package: +To ensure Nautobot Panorama ChatOps is automatically re-installed during future upgrades, create a file named `local_requirements.txt` (if not already existing) in the Nautobot root directory (alongside `requirements.txt`) and list the `nautobot-plugin-chatops-panorama` package: ```no-highlight # echo nautobot-plugin-chatops-panorama >> local_requirements.txt diff --git a/docs/index.md b/docs/index.md index 7652090..0f05684 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,4 +1,4 @@ -# Nautobot Plugin ChatOps Panorama +# Nautobot Panorama ChatOps This is a plugin for [Nautobot](https://github.com/nautobot/nautobot) that extends ChatOps support to Palo Alto Panorama systems. The plugin adds some useful commands into your ChatOps environment that enhance an administrator's and end user's day to day using of Panorama. This framework allows for the quick extension of new ChatOps commands for Panorama. @@ -32,7 +32,7 @@ pip install nautobot-plugin-chatops-panorama > The plugin is compatible with Nautobot 1.1.0 and higher -To ensure Nautobot Plugin ChatOps Panorama is automatically re-installed during future upgrades, create a file named `local_requirements.txt` (if not already existing) in the Nautobot root directory (alongside `requirements.txt`) and list the `nautobot-plugin-chatops-panorama` package: +To ensure Nautobot Panorama ChatOps is automatically re-installed during future upgrades, create a file named `local_requirements.txt` (if not already existing) in the Nautobot root directory (alongside `requirements.txt`) and list the `nautobot-plugin-chatops-panorama` package: ```no-highlight # echo nautobot-plugin-chatops-panorama >> local_requirements.txt