Slack¶

Table of Contents¶

Release Notes
Overview
- Key Features
Requirements
Installation
Function - Archive Slack Channel
Function - Post attachment to Slack
Function - Post message to Slack
Data Table - Slack Conversations
Playbooks
Troubleshooting & Support

Release Notes¶

Version	Notes
2.1.0	Add Playbooks
2.0.0	Migrated slackclient to v2, Added lookup via channel ID to improve speed
1.0.2	Support for App Host, proxy support added

fn_slack 2.1.0 Changes¶

In v2.1, the existing rules and workflows have been replaced with playbooks. This change is made to support the ongoing, newer capabilities of playbooks. Each playbook has the same functionality as the previous, corresponding rule/workflow.

If upgrading from a previous release, you’ll noticed that the previous release’s rules/workflows remain in place. Both sets of rules and playbooks are active. For manual actions, playbooks will have the same name as it’s corresponding rule, but with “(PB)” added at the end. For automatic actions, the playbooks will be disabled by default.

You can continue to use the rules/workflows. But migrating to playbooks will provide greater functionality along with future app enhancements and bug fixes.

fn_slack 2.0.0 Considerations¶

Slack integration is now able to use the channel ID instead of the channel name to post and archive. When using the channel name, this function must first retrieve a list of all channels in a workspace and then iterate through the list to find the desired channel. Using the channel ID, the function is able to immediately retrieve the desired channel and therefore is reccommended to use over channel name when calling functions via SOAR.

Overview¶

SOAR App for ‘fn_slack’

Function creates a Slack message based on a SOAR Incident, it’s Tasks, Notes, Artifacts and Attachments, exports conversation history from Slack channel to a text file, saves the text file as an Attachment and archives the Slack channel.

Key Features¶

Creating private or public channels
Inviting users to conversations
Preserving embedded links
Posting messages from Incidents, Notes, Artifacts and Tasks displaying authorship
Uploading Incident, Task or Artifact attachment
Exporting conversation history to a text file, saving it as an Attachment in SOAR and archiving Slack channel

Requirements¶

slackclient~=2.9.4

This app supports the IBM Security QRadar SOAR Platform and the IBM Security QRadar SOAR for IBM Cloud Pak for Security.

SOAR platform¶

The SOAR platform supports two app deployment mechanisms, App Host and integration server.

If deploying to a SOAR platform with an App Host, the requirements are:

SOAR platform >= 43.1.49.
The app is in a container-based format (available from the AppExchange as a zip file).

If deploying to a SOAR platform with an integration server, the requirements are:

SOAR platform >= 43.1.49.
The app is in the older integration format (available from the AppExchange as a zip file which contains a tar.gz file).
Integration server is running resilient_circuits>=45.0.0.
If using an API key account, make sure the account provides the following minimum permissions:

Name

Permissions

Org Data

Read

Function

Read

Name	Permissions
Org Data	Read
Function	Read

The following SOAR platform guides provide additional information:

App Host Deployment Guide: provides installation, configuration, and troubleshooting information, including proxy server settings.
Integration Server Guide: provides installation, configuration, and troubleshooting information, including proxy server settings.
System Administrator Guide: provides the procedure to install, configure and deploy apps.

The above guides are available on the IBM Documentation website at ibm.biz/soar-docs. On this web page, select your SOAR platform version. On the follow-on page, you can find the App Host Deployment Guide or Integration Server Guide by expanding Apps in the Table of Contents pane. The System Administrator Guide is available by expanding System Administrator.

Cloud Pak for Security¶

If you are deploying to IBM Cloud Pak for Security, the requirements are:

IBM Cloud Pak for Security >= 1.7
Cloud Pak is configured with an App Host.
The app is in a container-based format (available from the AppExchange as a zip file).

The following Cloud Pak guides provide additional information:

App Host Deployment Guide: provides installation, configuration, and troubleshooting information, including proxy server settings. From the Table of Contents, select Case Management and Orchestration & Automation > Orchestration and Automation Apps.
System Administrator Guide: provides information to install, configure, and deploy apps. From the IBM Cloud Pak for Security IBM Documentation table of contents, select Case Management and Orchestration & Automation > System administrator.

These guides are available on the IBM Documentation website at ibm.biz/cp4s-docs. From this web page, select your IBM Cloud Pak for Security version. From the version-specific IBM Documentation page, select Case Management and Orchestration & Automation.

Proxy Server¶

The app does support a proxy server.

Python Environment¶

Both Python 3.6 and Python 3.9 are supported. Additional package dependencies may exist for each of these packages:

resilient_circuits>=45.0.0
slackclient~=2.9.4

Endpoint Developed With¶

This app has been implemented using:

Product Name	Product Version	API URL	API Version
Slack	–	https://api.slack.com/	–

Prerequisites¶

Slack app OAuth Access Token

Installation¶

Install¶

To install or uninstall an App or Integration on the SOAR platform, see the documentation at ibm.biz/soar-docs.
To install or uninstall an App on IBM Cloud Pak for Security, see the documentation at ibm.biz/cp4s-docs and follow the instructions above to navigate to Orchestration and Automation.

App Configuration¶

The following table provides the settings you need to configure the app. These settings are made in the app.config file. See the documentation discussed in the Requirements section for the procedure.

Config	Required	Example	Description
api_token	Yes	`xoxb-xxxxxxxxx-xxxxxxxxxxxx-xxxxxxxxxxxxx-xxxxxxxxxxx`	Slack app OAuth Access Token
username	Yes	`IBM SOAR`	Username represents the default submission author. Using a bot token instead of a person token will overwrite the username, using the bot name instead when posting

The remainder of this section details the Slack configuration file changes.

It’s possible to override the template used for archiving a channel. Use the app.config setting: template_file=/var/rescircuits/slack_template.jinja2 to reference the template file named slack_template.jinja2 at location /var/rescircuits. See the default template referenced in the Template file section.

Function - Archive Slack Channel¶

Function exports conversation history from Slack channel to a text file, saves the text file as an Attachment and archives the Slack channel.

screenshot: fn-archive-slack-channel

Inputs:

Name	Type	Required	Example	Tooltip
`incident_id`	`number`	Yes	`-`	-
`slack_channel_id`	`text`	No	`Optional, faster`	Optional. Executing without channel ID archives the channel that this is associated with.
`task_id`	`number`	No	`-`	-

Outputs:

NOTE: This example might be in JSON format, but results is a Python Dictionary on the SOAR platform.

results = {
  "channel": "testv2"
}

Example Pre-Process Script:

# ID of this incident
inputs.incident_id = incident.id
inputs.slack_channel_id = rule.properties.slack_channel_id if rule.properties.slack_channel_id else inputs.slack_channel_id

Example Post-Process Script:

noteText = u"""Slack channel {} has been archived. The conversation history has been saved as an attachment.""".format(results.channel)
incident.addNote(helper.createRichText(noteText))

Function - Post attachment to Slack¶

Function uploads Incident, Task or Artifact Attachments to Slack channel.

screenshot: fn-post-attachment-to-slack

Inputs:

Name	Type	Required	Example	Tooltip
`artifact_id`	`number`	No	`-`	-
`attachment_id`	`number`	No	`-`	-
`incident_id`	`number`	Yes	`-`	-
`slack_channel`	`text`	No	`-`	Name of the existing or a new slack channel used to send message to. Channel names can only contain lowercase letters, numbers, hyphens, and underscores, and must be 21 characters or less.
`slack_channel_id`	`text`	No	`Optional`	Optional. Executing without channel ID archives the channel that this is associated with.
`slack_is_channel_private`	`boolean`	No	`-`	Indicate if the channel you are posting to should be private.
`slack_participant_emails`	`text`	No	`-`	Comma separated list of emails belonging to Slack users in your workspace that will be added to your channel.
`slack_text`	`text`	Yes	`-`	Text message or a container field to retain JSON fields to send to Slack.
`task_id`	`number`	No	`-`	-

Outputs:

NOTE: This example might be in JSON format, but results is a Python Dictionary on the SOAR platform.

results = {
  "channel": "testingv2",
  "url": "https://ibm-soar-test.slack.com/archives/C03QZGV0YJU/p1658330688241129"
}

Example Pre-Process Script:

#####################
# Attachment data   #
#####################

# Required inputs are: the incident id and attachment id
inputs.incident_id = incident.id
inputs.artifact_id = artifact.id

# Slack channel name
# Name of the existing Slack Workspace channel or a new Slack channel you are posting to.
# Channel names can only contain lowercase letters, numbers, hyphens, and underscores, and must be 21 characters or less.
# If you leave this field empty, function will try to use the slack_channel associated with the Incident or Task found in the Slack Conversations datatable.
# If there isn’t one defined, the workflow will terminate.
inputs.slack_channel = rule.properties.rule_slack_channel if rule.properties.rule_slack_channel is not None else inputs.slack_channel

# Is channel private
# Indicate if the channel you are posting to should be private.
inputs.slack_is_channel_private = rule.properties.rule_slack_is_channel_private if rule.properties.rule_slack_is_channel_private is not None else inputs.slack_is_channel_private

# Slack user emails
# Comma separated list of emails belonging to Slack users in your workspace that will be added to your channel.
inputs.slack_participant_emails = rule.properties.rule_slack_participant_emails if rule.properties.rule_slack_participant_emails is not None else inputs.slack_participant_emails

# Slack additional text message
# Additional text message to include with the Incident, Note, Artifact, Attachment or Task data.
inputs.slack_text = rule.properties.rule_slack_text if rule.properties.rule_slack_text is not None else ''

# Slack Channel ID, faster than finding via channel name
inputs.slack_channel_id = rule.properties.slack_channel_id if rule.properties.slack_channel_id else inputs.slack_channel_id

Example Post-Process Script:

users = ""
for user in results.user_info:
  users += "{} \n".format(user)
# Create a note
noteText = u"""Artifact Attachment was posted to <a href='{}'>Slack channel #{}</a>. Members of this channel are: \n{}""".format(results.url, results.channel, users)
incident.addNote(helper.createRichText(noteText))

Function - Post message to Slack¶

Function sends a message from an Incident, Task, Note or an Artifact to a Slack channel.

screenshot: fn-post-message-to-slack

Inputs:

Name	Type	Required	Example	Tooltip
`incident_id`	`number`	Yes	`-`	-
`slack_as_user`	`boolean`	No	`-`	Set to true and the authenticated user of the Slack App will appear as the author of the message, ignoring any values provided for slack_username.
`slack_channel`	`text`	No	`-`	Name of the existing or a new slack channel used to send message to. Channel names can only contain lowercase letters, numbers, hyphens, and underscores, and must be 21 characters or less.
`slack_channel_id`	`text`	No	`Optional`	Optional. Executing without channel ID archives the channel that this is associated with.
`slack_is_channel_private`	`boolean`	No	`-`	Indicate if the channel you are posting to should be private.
`slack_mrkdwn`	`boolean`	No	`-`	Disable Slack markup parsing by setting to false.
`slack_participant_emails`	`text`	No	`-`	Comma separated list of emails belonging to Slack users in your workspace that will be added to your channel.
`slack_text`	`text`	Yes	`-`	Text message or a container field to retain JSON fields to send to Slack.
`slack_username`	`text`	No	`-`	Set your Slack app’s name that will appear as the author of the message. Must be used in conjunction with slack_as_user set to false, otherwise ignored.
`task_id`	`number`	No	`-`	-

Outputs:

NOTE: This example might be in JSON format, but results is a Python Dictionary on the SOAR platform.

results = {
  "channel": "testingv2",
  "url": "https://ibm-soar-test.slack.com/archives/C03QZGV0YJU/p1658330751752819"
}

Example Pre-Process Script:

#####################
# Artifact data     #
#####################

# Slack additional text message
# Additional text message to include with the Incident, Note, Artifact, Attachment or Task data.
rule_additional_text = rule.properties.rule_slack_text if rule.properties.rule_slack_text is not None else ''

# Incident id for the URL
incident_id_str = str(incident.id)

# Slack text message in JSON format
# ---------------------------------
# Do not remove first 3 elements "Additional Text", "Resilient URL" and "Type of data",
# the information is used to generate the title of the message.
#
# Add/remove information using the syntax:
# "label": {{ "type": "[string|richtext|boolean|datetime", "data": "resilient field data" }}
#
# Make sure to send "datetime" types as integers and not strings:
# without double quotes: { "type": "datetime", "data": resilient datetime data}
#
# Text fields like 'artifact.value', or 'Slack additional text message' can include double quotes.
# Watch out for embedded double quotes in these text fields and escape with field.replace(u'"', u'\\"') otherwise json.loads will fail.
slack_text = u"""{{
  "Additional Text": {{"type": "string", "data": "{0}" }},
  "Resilient URL": {{"type": "incident", "data": "{1}" }},
  "Type of data": {{"type": "string", "data": "{2}" }},
  "Incident ID": {{"type": "string", "data": "{3}" }},
  "Artifact Type": {{"type": "string", "data": "{4}" }},
  "Artifact Value": {{"type": "string", "data": "{5}" }},
  "Artifact Created By": {{"type": "string", "data": "{6}" }},
  "Artifact Created on": {{"type": "datetime", "data": {7} }}
}}""".format(
  rule_additional_text.replace(u'"', u'\\"'),
  incident_id_str,
  "Artifact",
  incident_id_str,
  artifact.type,
  artifact.value.replace(u'"', u'\\"'),
  artifact.creator.display_name,
  artifact.created)

# ID of this incident
inputs.incident_id = incident.id

# Slack channel name
# Name of the existing Slack Workspace channel or a new Slack channel you are posting to.
# Channel names can only contain lowercase letters, numbers, hyphens, and underscores, and must be 21 characters or less.
# If you leave this field empty, function will try to use the slack_channel associated with the Incident or Task found in the Slack Conversations datatable.
# If there isn’t one defined, the workflow will terminate.
inputs.slack_channel = rule.properties.rule_slack_channel if rule.properties.rule_slack_channel is not None else inputs.slack_channel

# Is channel private
# Indicate if the channel you are posting to should be private.
inputs.slack_is_channel_private = rule.properties.rule_slack_is_channel_private if rule.properties.rule_slack_is_channel_private is not None else inputs.slack_is_channel_private

# Slack user emails
# Comma separated list of emails belonging to Slack users in your workspace that will be added to your channel.
inputs.slack_participant_emails = rule.properties.rule_slack_participant_emails if rule.properties.rule_slack_participant_emails is not None else inputs.slack_participant_emails

# Slack text message
# Container field to retain JSON fields to send to Slack.
inputs.slack_text = slack_text

# Slack Channel ID, faster than finding via channel name
inputs.slack_channel_id = rule.properties.slack_channel_id if rule.properties.slack_channel_id else inputs.slack_channel_id

Example Post-Process Script:

users = ""
for user in results.user_info:
  users += "{} \n".format(user)
# Create a note
noteText = u"""Artifact was posted to <a href='{}'>Slack channel #{}</a>. Members of this channel are: \n{}""".format(results.url, results.channel, users)
incident.addNote(helper.createRichText(noteText))

Data Table - Slack Conversations¶

API Name:¶

slack_conversations_db

Columns:¶

Column Name	API Access Name	Type	Tooltip
Resilient ID	`slack_db_res_id`	`text`	-
Slack channel name	`slack_db_channel`	`text`	-
Slack channel type	`slack_db_channel_type`	`text`	-
Slack URL	`slack_db_permalink`	`textarea`	-
Time	`slack_db_time`	`datetimepicker`	-

Playbooks¶

Rule Name	Object	Status
Slack: Archive Incident Slack Channel - Example (PB)	incident	`enabled`
Slack: Archive Task Slack Channel - Example (PB)	task	`enabled`
Slack: Post Artifact Attachment to Slack - Example (PB))	artifact	`enabled`
Slack: Post Artifact to Slack - Example (PB)	artifact	`enabled`
Slack: Post Incident / Task Attachment to Slack - Example (PB)	attachment	`enabled`
Slack: Post Incident to Slack - Example (PB)	incident	`enabled`
Slack: Post Note to Slack - Example (PB)	note	`enabled`
Slack: Post Task to Slack - Example (PB)	task	`enabled`

Troubleshooting & Support¶

Refer to the documentation listed in the Requirements section for troubleshooting information.

For Support¶

This is an IBM supported app. Please search ibm.com/mysupport for assistance.