# salt.engines.slack_bolt_engine

An engine that reads messages from Slack and can act on them

Added in version 3006.0.

depends:

  slack_bolt Python module

Important

This engine requires a Slack app and a Slack Bot user. To create a bot user, first go to the Custom Integrations page in your Slack Workspace. Copy and paste the following URL, and log in with account credentials with administrative privileges:

`https://api.slack.com/apps/new`

Next, click on the `From scratch` option from the `Create an app` popup. Give your new app a unique name, eg. `SaltSlackEngine`, select the workspace where your app will be running, and click `Create App`.

Next, click on `Socket Mode` and then click on the toggle button for `Enable Socket Mode`. In the dialog give your Socket Mode Token a unique name and then copy and save the app level token. This will be used as the `app_token` parameter in the Slack engine configuration.

Next, click on `Event Subscriptions` and ensure that `Enable Events` is in the on position. Then add the following bot events, `message.channel` and `message.im` to the `Subcribe to bot events` list.

Next, click on `OAuth & Permissions` and then under `Bot Token Scope`, click on `Add an OAuth Scope`. Ensure the following scopes are included:

> - `channels:history`

> - `channels:read`

> - `chat:write`

> - `commands`

> - `files:read`

> - `files:write`

> - `im:history`

> - `mpim:history`

> - `usergroups:read`

> - `users:read`

Once all the scopes have been added, click the `Install to Workspace` button under `OAuth Tokens for Your Workspace`, then click `Allow`. Copy and save the `Bot User OAuth Token`, this will be used as the `bot_token` parameter in the Slack engine configuration.

Finally, add this bot user to a channel by switching to the channel and using `/invite @mybotuser`. Keep in mind that this engine will process messages from each channel in which the bot is a member, so it is recommended to narrowly define the commands which can be executed, and the Slack users which are allowed to run commands.

This engine has two boolean configuration parameters that toggle specific features (both default to `False`):

1. `control` - If set to `True`, then any message which starts with the trigger string (which defaults to `!` and can be overridden by setting the `trigger` option in the engine configuration) will be interpreted as a Salt CLI command and the engine will attempt to run it. The permissions defined in the various `groups` will determine if the Slack user is allowed to run the command. The `targets` and `default_target` options can be used to set targets for a given command, but the engine can also read the following two keyword arguments:

   - `target` - The target expression to use for the command

   - `tgt_type` - The match type, can be one of `glob`, `list`, `pcre`, `grain`, `grain_pcre`, `pillar`, `nodegroup`, `range`, `ipcidr`, or `compound`. The default value is `glob`.

   Here are a few examples:

       !test.ping target=*
       !state.apply foo target=os:CentOS tgt_type=grain
       !pkg.version mypkg target=role:database tgt_type=pillar

2. `fire_all` - If set to `True`, all messages which are not prefixed with the trigger string will fired as events onto Salt's ref:event bus <event-system>. The tag for these events will be prefixed with the string specified by the `tag` config option (default: `salt/engines/slack`).

The `groups_pillar_name` config option can be used to pull group configuration from the specified pillar key.

Note

In order to use `groups_pillar_name`, the engine must be running as a minion running on the master, so that the `Caller` client can be used to retrieve that minion's pillar data, because the master process does not have pillar data.

## Configuration Examples

Changed in version 2017.7.0: Access control group support added

Changed in version 3006.0: Updated to use slack_bolt Python library.

This example uses a single group called `default`. In addition, other groups are being loaded from pillar data. The users and commands defined within these groups are used to determine whether the Slack user has permission to run the desired command.

    engines:
      - slack_bolt:
          app_token: "xapp-x-xxxxxxxxxxx-xxxxxxxxxxxxx-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
          bot_token: 'xoxb-xxxxxxxxxx-xxxxxxxxxxxxxxxxxxxxxxxx'
          control: True
          fire_all: False
          groups_pillar_name: 'slack_engine:groups_pillar'
          groups:
            default:
              users:
                - '*'
              commands:
                - test.ping
                - cmd.run
                - list_jobs
                - list_commands
              aliases:
                list_jobs:
                  cmd: jobs.list_jobs
                list_commands:
                  cmd: 'pillar.get salt:engines:slack:valid_commands target=saltmaster tgt_type=list'
              default_target:
                target: saltmaster
                tgt_type: glob
              targets:
                test.ping:
                  target: '*'
                  tgt_type: glob
                cmd.run:
                  target: saltmaster
                  tgt_type: list

This example shows multiple groups applying to different users, with all users having access to run test.ping. Keep in mind that when using `*`, the value must be quoted, or else PyYAML will fail to load the configuration.

    engines:
      - slack_bolt:
          groups_pillar: slack_engine_pillar
          app_token: "xapp-x-xxxxxxxxxxx-xxxxxxxxxxxxx-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
          bot_token: 'xoxb-xxxxxxxxxx-xxxxxxxxxxxxxxxxxxxxxxxx'
          control: True
          fire_all: True
          tag: salt/engines/slack
          groups_pillar_name: 'slack_engine:groups_pillar'
          groups:
            default:
              users:
                - '*'
              commands:
                - test.ping
              aliases:
                list_jobs:
                  cmd: jobs.list_jobs
                list_commands:
                  cmd: 'pillar.get salt:engines:slack:valid_commands target=saltmaster tgt_type=list'
            gods:
              users:
                - garethgreenaway
              commands:
                - '*'

class salt.engines.slack_bolt_engine.SlackClient(app_token, bot_token, trigger_string)
  can_user_run(user, command, groups)

    Check whether a user is in any group, including whether a group has the '*' membership

    Parameters:

      - user (str) -- The username being checked against

      - command (str) -- The command that is being invoked (e.g. test.ping)

      - groups (dict) -- the dictionary with groups permissions structure.

    Return type:

      tuple

    Returns:

      On a successful permitting match, returns 2-element tuple that contains the name of the group that successfully matched, and a dictionary containing the configuration of the group so it can be referenced.

      On failure it returns an empty tuple

  commandline_to_list(cmdline_str, trigger_string)

    cmdline_str is the string of the command line trigger_string is the trigger string, to be removed

  control_message_target(slack_user_name, text, loaded_groups, trigger_string)

    Returns a tuple of (target, cmdline,) for the response

    Raises IndexError if a user can't be looked up from all_slack_users

    Returns (False, False) if the user doesn't have permission

    These are returned together because the commandline and the targeting interact with the group config (specifically aliases and targeting configuration) so taking care of them together works out.

    The cmdline that is returned is the actual list that should be processed by salt, and not the alias.

  fire(tag, msg)

    This replaces a function in main called 'fire'

    It fires an event into the salt bus.

    Parameters:

      - tag (str) -- The tag to use when sending events to the Salt event bus.

      - msg (dict) -- The msg dictionary to send to the Salt event bus.

  format_return_text(data, function, **kwargs)

    Print out YAML using the block mode

    Parameters:

      - token -- The return data that needs to be formatted.

      - token -- The function that was used to generate the return data.

  generate_triggered_messages(token, trigger_string, groups, groups_pillar_name)

    slack_token = string trigger_string = string input_valid_users = set input_valid_commands = set

    When the trigger_string prefixes the message text, yields a dictionary of:

        {
            'message_data': m_data,
            'cmdline': cmdline_list, # this is a list
            'channel': channel,
            'user': m_data['user'],
            'slack_client': sc
        }

    else yields {'message_data': m_data} and the caller can handle that

    When encountering an error (e.g. invalid message), yields {}, the caller can proceed to the next message

    When the websocket being read from has given up all its messages, yields {'done': True} to indicate that the caller has read all of the relevant data for now, and should continue its own processing and check back for more data later.

    This relies on the caller sleeping between checks, otherwise this could flood

  get_config_groups(groups_conf, groups_pillar_name)

    get info from groups in config, and from the named pillar

    Parameters:

      - group_conf (dict) -- The dictionary containing the groups, group members, and the commands those group members have access to.

      - groups_pillar_name (str) -- can be used to pull group configuration from the specified pillar key.

  get_jobs_from_runner(outstanding_jids)

    Given a list of job_ids, return a dictionary of those job_ids that have completed and their results.

    Query the salt event bus via the jobs runner. jobs.list_job will show a job in progress, jobs.lookup_jid will return a job that has completed.

    Parameters:

      outstanding_jids (list) -- The list of job ids to check for completion.

    returns a dictionary of job id: result

  get_slack_channels(token)

    Get all channel names from Slack

    Parameters:

      token (str) -- The Slack token being used to allow Salt to interact with Slack.

  get_slack_users(token)

    Get all users from Slack

    Parameters:

      token -- The Slack token being used to allow Salt to interact with Slack.

  get_target(permitted_group, cmdline, alias_cmdline)

    When we are permitted to run a command on a target, look to see what the default targeting is for that group, and for that specific command (if provided).

    It's possible for `None` or `False` to be the result of either, which means that it's expected that the caller provide a specific target.

    If no configured target is provided, the command line will be parsed for target=foo and tgt_type=bar

    Test for this:

        h = {'aliases': {}, 'commands': {'cmd.run', 'pillar.get'},
            'default_target': {'target': '*', 'tgt_type': 'glob'},
            'targets': {'pillar.get': {'target': 'you_momma', 'tgt_type': 'list'}},
            'users': {'dmangot', 'jmickle', 'pcn'}}
        f = {'aliases': {}, 'commands': {'cmd.run', 'pillar.get'},
             'default_target': {}, 'targets': {},'users': {'dmangot', 'jmickle', 'pcn'}}

        g = {'aliases': {}, 'commands': {'cmd.run', 'pillar.get'},
             'default_target': {'target': '*', 'tgt_type': 'glob'},
             'targets': {}, 'users': {'dmangot', 'jmickle', 'pcn'}}

    Run each of them through `get_configured_target(('foo', f), 'pillar.get')` and confirm a valid target

    Parameters:

      - permitted_group (tuple) -- A tuple containing the group name and group configuration to check for permission.

      - cmdline (list) -- The command sent from Slack formatted as a list.

      - alias_cmdline (str) -- An alias to a cmdline.

  message_text(m_data)

    Raises ValueError if a value doesn't work out, and TypeError if this isn't a message type

    Parameters:

      m_data (dict) -- The message sent from Slack

  message_trigger(message)
  parse_args_and_kwargs(cmdline)
    Parameters:

      cmdline (list) -- The command sent from Slack formatted as a list.

    returns tuple of: args (list), kwargs (dict)

  run_command_async(msg)
    Parameters:

      msg (dict) -- The message dictionary that contains the command and all information.

  run_commands_from_slack_async(message_generator, fire_all, tag, control, interval=1)

    Pull any pending messages from the message_generator, sending each one to either the event bus, the command_async or both, depending on the values of fire_all and command

    Parameters:

      - message_generator (generator of dict) -- Generates messages from slack that should be run

      - fire_all (bool) -- Whether to also fire messages to the event bus

      - control (bool) -- If set to True, whether Slack is allowed to control Salt.

      - tag (str) -- The tag to send to use to send to the event bus

      - interval (int) -- time to wait between ending a loop and beginning the next

salt.engines.slack_bolt_engine.start(app_token, bot_token, control=False, trigger='!', groups=None, groups_pillar_name=None, fire_all=False, tag='salt/engines/slack')

  Listen to slack events and forward them to salt, new version

  Parameters:

    - app_token (str) -- The Slack application token used by Salt to communicate with Slack.

    - bot_token (str) -- The Slack bot token used by Salt to communicate with Slack.

    - control (bool) -- Determines whether or not commands sent from Slack with the trigger string will control Salt, defaults to False.

    - trigger (str) -- The string that should preface all messages in Slack that should be treated as commands to send to Salt.

    - group (str) -- The string that should preface all messages in Slack that should be treated as commands to send to Salt.

    - group_pillars -- A pillar key that can be used to pull group configuration.

    - fire_all (bool) -- If set to `True`, all messages which are not prefixed with the trigger string will fired as events onto Salt's ref:event bus <event-system>. The tag for these events will be prefixed with the string specified by the `tag` config option (default: `salt/engines/slack`).

    - tag (str) -- The tag to prefix all events sent to the Salt event bus.