Merge pull request #25 from nzlosh/plugin_prefix

Fixes #24 - Convert all bot commands to dynamic plugin commands.

CHANGELOG.md

@@ -4,6 +4,28 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
 
+##  [2.1.2] 2019-11-24
+### Added
+  - Added CircleCI build badge to README.
+  - Added route key to be defined by user to allow mutliple bots attached to a single StackStorm instance.
+  - Added version check on start-up to log if newer version of the plugin are available.
+
+### Changed
+  - Updated curl example in troubleshooting section.
+  - Changed all bot commands to be registered dynamically to allow user defined plugin prefix.
+
+##  [2.1.1] 2019-07-19
+### Added
+  - Added configuration for mattermost, rocketchat, discord, gitter and slack to docker build.
+
+### Changed
+  - Improved Discord Chat Adapter formatting.
+  - Corrected configuration name handling which caused exceptions to be raised.
+  - Updated documentation to direct readers to readthedocs.
+
+### Removed
+  - Removed old readme file.
+
 ## [2.1.0] 2019-07-08
 ### Added
   - Added `deactivate` method to correctly handle errbot reload and stop process.

docs/authn.rst

@@ -0,0 +1,137 @@
+.. _authentication:
+
+***************
+Authentication
+***************
+
+.. contents:: :local:
+
+.. important:: Do not configure multiple authentication methods at the same time.
+
+Standalone
+==========
+
+This is the default authentication method where `err-stackstorm` uses its own credentials for all calls to the StackStorm API.  All action-aliases issued by chat service users execute the underlying workflows with `err-stackstorm` credentials.
+
+Any Role Based Access Control policies can only be applied to the bot user which gives limited control.
+
+Configuration
+--------------
+
+An empty dictionary in the `standalone` key is all that is required to maintain err-stackstorm's default authentication method.
+
+.. code-block:: python
+
+    "rbac_auth": {
+        "standalone": {}
+    }
+
+Client-Side
+============
+
+.. note::  This implementation is specific to err-stackstorm.
+
+`err-stackstorm` provides a way to associate the chat service user account with a StackStorm username/password or API token. Once a chat user is associated with their StackStorm credentials, any action-alias will be executed using the associated StackStorm credentials.
+
+This method allows for finer control as StackStorm's Role Based Access Control can be defined per-user.
+
+Chat users create a new authentication session with `err-stackstorm` by calling `session_start` with a secret word, it can be any thing the user wishes.  A `UUID <https://en.wikipedia.org/wiki/Universally_unique_identifier>`_ is generated for the session and the chat user is invited to follow a URL to an authentication page hosted by Errbot.
+
+.. important:: For security reasons, the UUID is used only once and is consumed when the page is accessed.  Any subsequent attempts to access the authentication page using the same link will result in an error.
+
+The login page must be protected by TLS encryption and ideally require an SSL client certificate.  The login page should not be exposed directly to the internet, but have a reverse proxy such as nginx placed between it and any external service consumers.
+
+The user enters their StackStorm credentials via the login page which err-stackstorm will validate against the StackStorm API.  If the credentials are valid, the user token or api key will be cached by err-stackstorm and the supplied credentials discarded.
+
+
+Configuration
+-------------
+
+To configure the Client-Side authentication method, one needs to take steps to setup both Nginx and Errbot. Nginx is used to serve static web content for the authentication web page and Errbot serves as the API backend for authentication calls.
+
+
+NGINX
+^^^^^^
+
+.. note:: This example is provided as a guide only.  You are expected to know and understand how to configure nginx for your environment.  It is outside of the scope of this documentation to go over nginx's configuration and explain SSL certificates.
+
+.. important::  This example does not show how to secure access using SSL certificates.  It is **highly recommended** to use SSL for production environments.
+
+To help understand the example below, the following conditions are assumed:
+
+* the nginx server is running *on the same host* as errbot.
+* the host's fully qualified domain name is ``my_host.my_fqdn``.
+* nginx listens to standard SSL-enabled port: 443.
+* Errbot's webserver listens on the ip address 127.0.0.1 TCP port 3141 without ssl enabled.
+* Errbot's plugins directory is /data/errbot/plugins
+* `err-stackstorm` is installed in /data/errbot/plugins/nzlosh/err-stackstorm.
+* The SSL certificate and private key used by nginx are called errbot.crt and errbot.key.
+
+.. code-block:: nginx
+
+    server {
+      listen       my_host.my_fqdn:443 ssl;
+      server_name  my_host.my_fqdn;
+
+      ssl on;
+
+      ssl_certificate           /etc/ssl/errbot.crt;
+      ssl_certificate_key       /etc/ssl/errbot.key;
+      ssl_session_cache         shared:SSL:10m;
+      ssl_session_timeout       5m;
+      ssl_protocols             TLSv1 TLSv1.1 TLSv1.2;
+      ssl_ciphers               EECDH+AESGCM:EDH+AESGCM:AES256+EECDH:AES256+EDH:ECDHE-RSA-AES128-GCM-SHA384:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA128:DHE-RSA-AES128-GCM-SHA384:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES128-GCM-SHA128:ECDHE-RSA-AES128-SHA384:ECDHE-RSA-AES128-SHA128:ECDHE-RSA-AES128-SHA:ECDHE-RSA-AES128-SHA:DHE-RSA-AES128-SHA128:DHE-RSA-AES128-SHA128:DHE-RSA-AES128-SHA:DHE-RSA-AES128-SHA:ECDHE-RSA-DES-CBC3-SHA:EDH-RSA-DES-CBC3-SHA:AES128-GCM-SHA384:AES128-GCM-SHA128:AES128-SHA128:AES128-SHA128:AES128-SHA:AES128-SHA:DES-CBC3-SHA:HIGH:!aNULL:!eNULL:!EXPORT:!DES:!MD5:!PSK:!RC4;
+      ssl_prefer_server_ciphers on;
+
+      index  index.html index.htm;
+
+      access_log            /var/log/nginx/ssl-errbot.access.log combined;
+      error_log             /var/log/nginx/ssl-errbot.error.log;
+
+      add_header              Front-End-Https on;
+      add_header              X-Content-Type-Options nosniff;
+
+      location /login/ {
+        proxy_pass            http://127.0.0.1:3141$request_uri;
+        proxy_read_timeout    90;
+        proxy_connect_timeout 90;
+        proxy_redirect        off;
+
+        proxy_set_header      Host my_host.my_fqdn;
+        proxy_set_header      X-Real-IP $remote_addr;
+        proxy_set_header      X-Forwarded-For $proxy_add_x_forwarded_for;
+
+        proxy_set_header Connection '';
+        chunked_transfer_encoding off;
+        proxy_buffering off;
+        proxy_cache off;
+        proxy_set_header Host my_host.my_fqdn;
+      }
+
+      location / {
+        root      /data/errbot/plugins/nzlosh/err-stackstorm/html/;
+        index     index.html index.htm;
+      }
+    }
+
+After successfully setting up nginx, the client side authentication url would be ``https://my_host.my_fqdn:443``.
+
+err-stackstorm configuration
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A url is required to correctly configure client-side authentication for ChatOps. This URL is Errbot's authentication endpoint that you have just set up.
+
+.. code-block:: python
+
+    "rbac_auth": {
+        "clientside": {
+            "url": "https://<hostname>:<port>/"
+        }
+    },
+
+Authenticating
+^^^^^^^^^^^^^^^
+
+Once the client side authentication is setup, you should be able to trigger the authentication process with ``!st2session_start my_secret_word`` which will return a url to complete the login processes. This is how the page looks like:
+
+.. image:: images/authentication_screen.jpg

docs/authz.rst

@@ -0,0 +1,53 @@
+.. _authorisation:
+
+***************
+Authorisation
+***************
+
+.. contents:: :local:
+
+
+Errbot Access Control List
+==========================
+
+Errbot comes with native Access Control List support.  It can be configured to constrain command execution by grouping ``command``, ``channel`` and ``user``.  Glob patterns can be used in each field to provide flexibility in ACL definitions.
+
+As an example, a StackStorm instance has an automatic package upgrade workflow.  Its progress can be viewed by executing the action alias: ``apu stats <role>``, which is defined as shown below::
+
+    | action_ref    | st2_apu.apu_status                                           |
+    | formats       | [                                                            |
+    |               |     {                                                        |
+    |               |         "representation": [                                  |
+    |               |             "apu status {{role}}"                            |
+    |               |         ],                                                   |
+    |               |         "display": "apu status <role>"                       |
+    |               |     }                                                        |
+    |               | ]                                                            |
+
+The Errbot ACL configuration below allows ``@user1`` to view the status of the upgrade, but *not to start/stop* the upgrade process, which are other action-aliases that are triggered with ``st2 apu ...``)
+
+.. code-block:: python
+
+    ACL_SQUAD_INFRA = ["@admin1", "@admin2", "@admin3", "@admin4"]
+    ACL_APU_USERS = ['@user1']
+    ACL_EVERYONE = ["*"]
+    ACCESS_CONTROLS = {
+        'whoami': {
+            'allowrooms': ['@bot_user'],
+            'allowusers': ACL_EVERYONE
+        },
+        'st2 apu status*':{
+            'allowrooms': ['#channel'],
+            'allowusers': ACL_SQUAD_INFRA + ACL_APU_USERS
+        },
+        'st2 apu*':{
+            'allowrooms': ['#channel'],
+            'allowusers': ACL_SQUAD_INFRA
+        },
+    }
+
+Getting the correct usernames to fill into ``allowusers`` or ``denyusers`` isn't always obvious.  Use errbot's ``!whoami`` command to get the correct username for use within ACL definitions.  The `nick` value is what should be used in the configuration in the case of Slack.
+
+.. warning:: UI interface names do not always match with the internal nickname/username. ``!whoami`` is a surefire way of retrieving the correct username.
+
+On a small scale it's possible to use the ``!whoami`` command to get the correct user account name but for large installations it'd make more sense to use pre-defined patterns.

docs/configuration.rst

@@ -21,7 +21,8 @@ Here's a sample err-stackstorm configuration:
         'auth_url': 'https://your.stackstorm.com/auth/v1',
         'api_url': 'https://your.stackstorm.com/api/v1',
         'stream_url': 'https://your.stackstorm.com/stream/v1',
-
+        'route_key': 'errbot',
+        'plugin_prefix': 'st2',
         'verify_cert': True,
         'secrets_store': 'cleartext',
         'api_auth': {
@@ -52,6 +53,7 @@ Edit the ``/<st2>/packs/chatops/actions/post_message.yaml`` file and replace `ch
   route:
     default: "errbot"
 
+.. note:: See Route Key below for information on customising the route.
 
 Authentication
 ---------------
@@ -105,14 +107,24 @@ Cleartext
 
 The cleartext store maintains the cache in memory and does not encrypt the contents to disk. It **does not** protect the stored secrets in memory.
 
+Route Key
+---------
+
+StackStorm ChatOps uses `routes` to indicate where a notification should be sent.  By default the StackStorm ChatOps pack uses **chatops** as the route kei to send messages when an action result is posted.  It is possible to run more than one errbot instance per StackStorm instance by configuring different route keys.  Such a feature would allow running one errbot instance that listens on Slack and another that listens on Discord, where both would expose StackStorm's action-aliases.
+
+Plugin Prefix
+-------------
+
+Errbot detects commands using a **bot_plugin** prefix, often ``!`` character.  Errbot functionality is extended through plugins.  Plugins register new commands with Errbot as they are loaded.  Err-stackstorm is a plugin and adds a special command for calling StackStorm Action-Aliases.  To avoid name collisions between *Errbot Commands* and *StackStorm Action-Aliases*, a **plugin_prefix** is used which is ``st2`` by default.  The plugin_prefix can be customised to be any string, but be careful not to use strings that conflict with existing commands.
+
 Locale
 -------
 
 Errbot uses the system's locale for handling text. If you're getting unicode errors like this::
 
   UnicodeEncodeError: 'ascii' codec can't encode character '\xe9' in position 83: ordinal not in range(128)
 
-Make sure the systems locale is configured for unicode encoding. In the example below, the machine has set the English (en) New Zealand (NZ) with utf-8 encoding (.UTF8).
+Make sure the systems locale is configured for unicode encoding. In the example below, the machine has been set to English (en) New Zealand (NZ) with utf-8 encoding (.UTF8).
 
 .. code-block:: bash
 
@@ -142,15 +154,17 @@ Reference
     :header: "Option", "Description"
     :widths: 25, 40
 
-    "auth_url", "StackStorm's authentication url end point. Used to authenticate credentials against StackStorm."
-    "api_url", "StackStorm's API url end point. Used to execute action aliases received from the chat back-end."
-    "stream_url", "StackStorm's Stream url end point. Used to received ChatOps notifications."
-    "verify_cert", "Default is *True*. Verify the SSL certificate is valid when using https end points. Applies to all end points."
+    "auth_url", "StackStorm's authentication url end point.  Used to authenticate credentials against StackStorm."
+    "api_url", "StackStorm's API url end point.  Used to execute action aliases received from the chat back-end."
+    "stream_url", "StackStorm's Stream url end point.  Used to received ChatOps notifications."
+    "verify_cert", "Default is *True*.  Verify the SSL certificate is valid when using https end points. Applies to all end points."
+    "route_key", "Default is *errbot*. The name of the route to bot will listen for and submit action-alias executions with."
+    "plugin_prefix", "Default is *st2*. Text used to prefix action-alias commands with to avoid name collisions between StackStorm Action-Aliases and Errbot plugin commands."
     "api_auth.user.name", "Errbot's username to authenticate with StackStorm."
     "api_auth.user.password", "Errbot's password to authenticate with StackStorm."
     "api_auth.token", "Errbot's user token to authenticate with StackStorm. Used instead of a username/password pair."
     "api_auth.apikey", "Errbot API key to authenticate with StackStorm. Used instead of a username/password pair or user token."
-    "timer_update", "Unit: seconds. Default is 60. Interval for err-stackstorm to the user token is valid."
+    "timer_update", "Unit: seconds. Default is 60. Interval to test if err-stackstorm's user token is valid."
     "rbac_auth.standalone", "Standalone authentication."
     "rbac_auth.clientside", "Clientside authentication, a chat user will supply StackStorm credentials to err-stackstorm via an authentication page."
     "rbac_auth.clientside.url", "Url to the authentication web page."

docs/getting_started.rst

@@ -9,33 +9,34 @@ Getting Started
 Overview
 =========
 
-`err-stackstorm` is an unofficial community project to bring StackStorm ChatOps to Errbot. Using `err-stackstorm` you will be able to leverage `Errbot <http://errbot.io/en/latest/index.html>`_ as the `ChatOps <https://docs.stackstorm.com/chatops/index.html>`_ of your choice for controlling Stackstorm using **conversation-driven development** by using Stackstorm's `Action Aliases <https://docs.stackstorm.com/chatops/aliases.html>`_.
+`err-stackstorm` is a community project to bring StackStorm `ChatOps <https://docs.stackstorm.com/chatops/index.html>`_ to `Errbot <http://errbot.io/en/latest/index.html>`_.  No commercial support is provided by StackStorm.  `err-stackstorm` exposes Stackstorm's `Action Aliases <https://docs.stackstorm.com/chatops/aliases.html>`_ to your chat environment, where you and your team can manage aspects of infrastructure and code.
 
+The objectives for err-stackstorm project are:
  1. Emulate hubot-stackstorm features.
  2. Provide a Python friendly ChatOps solution.
  3. Respect StackStorm's enterprise offering.
  4. Maintain the same high quality as the StackStorm project.
  5. Collaborate with the StackStorm community to evolve ChatOps features.
 
-.. important:: `st2chatops` does not have to be running on your StackStorm instance. This plugin *replaces* `st2chatops`.
-
 Features
 ========
 
 err-stackstorm communicates directly with the StackStorm API from with an errbot instance.
 
-     - List action-alias help dynamically. When StackStorm action-aliases are updated, they are immediately available in the err-stackstorm output. Filtering by pack name and keyword can be used when look for help.
+     - List action-alias help dynamically.  When StackStorm action-aliases are updated, they are immediately available in the err-stackstorm output.  Filtering by pack name and keyword can be used when looking for help.
      - Access-Control Lists based on any combination of chat username, command and room. ACLs are defined in the errbot configuration file.
-     - Associate StackStorm user credentials with chat usernames.  Client-Side authenticate lets err-stackstorm dynamically map chat user accounts with StackStorm authenicated users via an authenticationn web page.
+     - Associate StackStorm user credentials with chat usernames.  Client-Side authenticate lets err-stackstorm dynamically map chat user accounts with StackStorm authenicated users.  Credentials are passed via an out of band authentication web page.
      - Trigger action-aliases directly from the bot.
      - Support for multiple chat backends, as provided by errbot.
+     - Customise plugin prefix.
+     - Customise StackStorm route key to allow more than one bot to be connected to a single StackStorm instance.
      - Docker image available to get up and running quickly and easily.
      - Python based using modern 3.6 features.
 
 Compatibility
 ==============
 
-The plugin has been developed and tested against the below software combinations. Because you might be running different Python or Errbot versions, we provide here the combinations to achieve optimal operation:
+The plugin has been developed and tested against the below software combinations. Because you might be running different Python or Errbot versions, the below are the optimal combinations:
 
 
    .. csv-table:: Ideal Combination of Versions

docs/index.rst

@@ -8,7 +8,7 @@
 Welcome to err-stackstorm's documentation!
 ==========================================
 
-err-stackstorm is an unofficial community project to bring StackStorm ChatOps to Errbot.
+err-stackstorm is a community project to bring StackStorm ChatOps to Errbot.  No commercial support is provided by StackStorm.
 
 .. toctree::
    :maxdepth: 2
@@ -18,7 +18,8 @@ err-stackstorm is an unofficial community project to bring StackStorm ChatOps to
    quick_start.rst
    installation.rst
    configuration.rst
-   rbac.rst
+   authn.rst
+   authz.rst
    action_aliases.rst
    troubleshooting.rst
    project.rst

docs/installation.rst

@@ -48,7 +48,8 @@ Paste the sample configuration below in Errbot's ``config.py`` file adjusting th
         'auth_url': 'https://your.stackstorm.com/auth/v1',
         'api_url': 'https://your.stackstorm.com/api/v1',
         'stream_url': 'https://your.stackstorm.com/stream/v1',
-
+        'route_key': 'errbot',
+        'plugin_prefix': 'st2',
         'verify_cert': True,
         'secrets_store': 'cleartext',
         'api_auth': {
@@ -62,8 +63,7 @@ Paste the sample configuration below in Errbot's ``config.py`` file adjusting th
         'rbac_auth': {
             'standalone': {},
         },
-        'timer_update': 900, #  Unit: second.  Interval to check the user token
-        is still valid.
+        'timer_update': 900, #  Unit: second.  Interval to check the user token is still valid.
     }