FortiSOAR For Slack Application v1.0.0

About the FortiSOAR For Slack Application

The FortiSOAR for Slack application (app) builds a bridge for seamless integration with FortiSOAR, allowing you to leverage the power of FortiSOAR as part of your daily communications and threat investigation routines.

The FortiSOAR For Slack app enables end-to-end communication with Slack. You can add the integration app to your Slack workspace to use the Slack integrations that are currently available:

• Slash Commands: Trigger FortiSOAR workflows by running slash commands or adding @ mentions in Slack. The list of supported slash commands is as follows:
  • /fortisoar help command to display the available commands and their usage details.
  • /fortisoar availableCommands command to list all the available tags labels that can be used in commands for triggering playbooks.
  • /fortisoar createAlert command to create an alert in FortiSOAR using the alert creation form.
  • /fortisoar createIndicator command to create an indicator in FortiSOAR. Optionally, you can add an indicator value to this command, in the format, /fortisoar createIndicator <indicator_value> to add an indicator in FortiSOAR and get the latest enrichment back to Slack within seconds.
  • /fortisoar invokePlaybook <nameOfTagDefinedForCommand> command to trigger a playbook in FortiSOAR. You must ensure that playbooks that require to be triggered from Slack have the default bot_enabled tag added to the playbooks.
    An Example: A playbook used for getting IP reputation contains the tags 'getIPRep', and the default 'bot_enabled'. To trigger this playbook from Slack, use the /fortisoar invokePlaybook getIPRep command.
• Manual Inputs: 'Slack' can be used as a channel for the delivery of manual input prompts to achieve seamless integration between Slack and FortiSOAR. You can trigger manual input playbooks in FortiSOAR, send the manual input form to users on Slack to get their responses, and based on the responses, resume the playbooks in FortiSOAR.

Version Information:

FortiSOAR For Slack Application Version: 1.0.0

FortiSOAR™ Version Tested on: 7.3.1

Slack connector Version Tested on: 3.0.0

Authored By: Fortinet

Adding the FortiSOAR For Slack Application to your Slack workspace

1. Login to api.slack.com using your Slack account credentials.
2. On the top bar, click Your apps > Create New App to display the Create an App dialog.
3. On the Create an App dialog, select the From an app manifest option.
   
4. On the Pick a workspace to develop your app dialog, select the workspace in which you want to develop the FortiSOAR For Slack app:
   
5. Download the attached 'fortisoar_manifest.zip' file and extract the fortisoar_manifest.yml file.
6. Copy the contents of the fortisoar_manifest.yml file in the Enter app manifest below dialog and then click Next.
   
7. On the Review summary & create your app dialog, you can review the permissions required by the app on the OAuth tab, the overview of the functionalities provided by the app, such as the slack commands and shortcuts provided, etc on the Features tab, and the events on which the app is subscribed, on the Settings tab. Once you have reviewed the app, click Create:
   
   This creates the app named 'FortiSOAR For Slack' in your workspace and opens the Basic Information page of the app.
8. On the Basic Information page of the app, scroll to the App-Level Tokens section to generate an app-level token and scopes for the FortiSOAR For Slack application. In the App-Level Tokens section, click Generate Token and Scopes, and do the following in the Generate an app-level token dialog:
   1. In the Token Name field, enter the name that you want to assign to the token, for example, enter FortiSOAR Integration.
   2. Click Add Scopes, and from the drop-down list, select connections:write, and then click Generate. connections:write is the mandatory and minimum-required permission for the app.
      
      This generates the App-level token for your FortiSOAR For Slack app:
      You require the App-level token to configure the Slack connector.
9. To add the logo for the FortiSOAR For Slack app, do the following:
   1. Download the attached 'FortiSOARForSlackApp_Logo.zip' file and extract the FortiSOARForSlackApp_Logo.png file.
   2. On the Basic Information page of the app, scroll to the Display Information section and click the Add Icon box in the App icon & Preview field. This opens a 'Browse' dialog.
   3. Navigate to the path you have extracted the logo (FortiSOARForSlackApp_Logo.png), select the logo, and click Open.
      This adds the logo for your FortiSOAR For Slack app.
   4. Click Save Changes to save your changes.
10. To install the FortiSOAR For Slack app on your channels, do the following:
    1. On the Basic Information page, from the Settings menu, click Install app.
    2. On the Install App to Your Team page, click Install to Workspace, which displays a page containing information about the app.
    3. From the Search for Channel drop-down list, select the channel that will be used to perform various interactions between FortiSOAR and Slack, and click Allow:
       

Configuring the FortiSOAR For Slack Application in your FortiSOAR instance

IMPORTANT: The bi-directional communication between Slack and FortiSOAR is supported only on FortiSOAR nodes, i.e., this feature is currently not supported on FSR Agent nodes. Also, bi-directional communication between Slack and FortiSOAR is not supported in an air-gapped environment.

1. Ensure that you have installed the FortiSOAR For Slack Solution Pack using Content Hub in your FortiSOAR instance. For more information on the FortiSOAR For Slack Solution Pack, see the Content Hub Portal.
   In brief, the FortiSOAR For Slack Solution Pack does the following:
   • Installs the Slack connector. The FortiSOAR For Slack Application is supported on version 3.0.0 or later of the Slack connector.
   • Adds the following new channels to 'Notifications':
     • Slack Link Channel: Used to send a message to Slack when a predefined rule is met.
     • Slack channel: Used to send the manual input form to Slack.
   • Adds the following new delivery rules:
     • Slack > Notify For External Manual Input: Used to send the manual input form to Slack.
     • Slack > Send Manual Input Link To Slack: Used to send a link that contains the manual input form to Slack.
     • Slack > Notify On Playbook Failure: Use to display a message on Slack for playbook failures.
   • Adds a playbook collection name "02 - Use Case - FortiSOAR for Slack" that contains playbooks to support triggering the /fortisoar createAlert and /fortisoar createIndicator commands on Slack to create an alert or indicator in FortiSOAR. It also contains a playbook that can be triggered from Slack to enrich an IP address.
   • Adds a new system picklist named 'External Channel' used to display the supported external channel options in the Manual Input step. Currently, 'Email' and 'Slack' are the channels that can be used to get inputs from users outside FortiSOAR using Manual Inputs.
2. Ensure that version 3.0.0 or later of the Slack connector is configured. For more information, see the Slack Connector document on the FortiSOAR Connectors page.
   To configure the connector, open the Slack connector, and in the Slack Connector Configurations popup, you require to do the following:
   1. In the OAuth Token field, enter the OAuth token of your FortiSOAR For Slack app.
      You can get the OAuth token that contains the required scopes that are configured for your account when you add the FortiSOAR For Slack app to your Slack workspace. For more information, see Adding the FortiSOAR For Slack App to your Slack workspace section.
      The OAuth token is visible on the FortiSOAR For Slack application page in api.slack.com. From the menu, click Features > OAuth & Permissions to display the OAuth & Permissions page:
      
      Copy the 'OAuth Token' from the Bot Use OAuth Token field and paste that token into the OAuth Token field in the Configurations popup. The OAuth token starts with xoxb- or xoxp-
   2. Select the Enable Bot Communication checkbox and enter the following details:
      1. In the App Level Token field, enter the app-level token for the FortiSOAR For Slack app.
         You can get the app-level token that contains when you add the FortiSOAR For Slack app to your Slack workspace. For more information, see Adding the FortiSOAR For Slack App to your Slack workspace section.
         The App-level token is visible on the FortiSOAR For Slack application page in api.slack.com. From the menu, click Basic Information and scroll to the App-Level Tokens section. From the Tokens section, click the name of the token that you had specified for the FortiSOAR For Slack app, for example, FortiSOAR Integration. Copy the token and paste that token into the App Level Token field in the Configurations popup. The App Level token starts with xapp-
         
         NOTE: The FortiSOAR For Slack application only requires the "connections:write" scope.
         The Configurations popup for the Slack connector appears as follows on your FortiSOAR instance:
         
3. To enable Manual Inputs delivery and response on the Slack channel, ensure that you configure manual inputs appropriately. For more information, see the Example of running a Manual Input playbook that uses Slack as a delivery medium topic and the 'Manual' Inputs topic in the Triggers & Steps chapter of the Playbooks Guide, which is part of the FortiSOAR Product Documentation.

FortiSOAR-Slack Application Usage

Once you have completed adding the FortiSOAR For Slack application to your Slack workspace and channel, configured the Slack connector, and installed the FortiSOAR For Slack Solution pack, the bridge enabling integration of FortiSOAR with Slack is ready for end-to-end communication between FortiSOAR and Slack. For our example, we have added the FortiSOAR For Slack application in a workspace named 'Demo' and the channel named 'fortisoar-integration'.

Once you have added the app, you will see FortiSOAR in Apps in your 'Slack' app:

The Home tab provides you with information about the app and also gives you information on how to get started and use the FortiSOAR For Slack app, i.e., it lists the 'Slash' commands supported.

If you need any help at any time with the supported 'Slash' commands or the list of tags labels that can be used to trigger playbooks, you can type the /fortisoar help or /fortisoar availableCommands respectively in your configured channel, 'fortisoar-integration' channel in our example. The following image displays the list of commands that can be used to trigger playbooks from Slack:

You can also use '@' mentions to run the commands, for example, typing @fortisoar help also displays information about the supported commands.
Note: '@' mentions work only when you type commands in the 'Channels'; and is not supported while typing commands in 'Messages'.
When you use @ mentions, conversation threads are created, for example, typing @fortisoar availableCommands displays the 'Thread' on the right of your Slack app:

To know the available shortcuts, type / in the 'fortisoar-integration' channel to display the Search shortcuts dialog and select the FortiSOAR For Slack option:

Alternatively, you can also type /<nameOfTheOperation> for example /create to get a list of all the commands that perform the creation action. The actions that are appended with 'FortiSOAR For Slack' are the actions that have been added by the app, for example, 'Create Alert with FortiSOAR For Slack':

The various integrations between Slack and FortiSOAR are achieved using FortiSOAR Playbooks; therefore, you can view the progress of integration using the 'Executed Playbook Logs' in FortiSOAR.

Example of adding an alert or indicator using the 'Slash' commands

Adding an alert

To quickly add an alert in FortiSOAR using the slash command, in your 'fortisoar-integration' channel, type /fortisoar createAlert in the 'fortisoar-integration' channel:

This displays the following input form in which you can fill in details to create the alert in FortiSOAR:

Once you complete filling in the details click Create Alert, which displays a message such as 'Input submitted successfully', and then adds the alert in FortiSOAR:

The Messages tab of the FortiSOAR app in Slack also displays messages for the successful execution of actions or appropriate error messages for failures of actions. For example, once the alert is added in FortiSOAR, a message such as "Done! Alert 'Test Alert' successfully created. View Alert", is shown on the Message tab:

Similarly, you can add an indicator in FortiSOAR by running the /fortisoar createIndicator command in the 'fortisoar-integration' channel. This command displays an indicator creation input form that you can fill out and submit the indicator.

Adding an indicator with the indicator value specified

To quickly add an indicator in FortiSOAR by specifying the indicator value in the slash command itself, so that the input form does not need to be displayed, type the /fortisoar createIndicator <indicatorValue>, for example, type the /fortisoar createIndicator gumblar.cn command in the 'fortisoar-integration' channel:

This adds an indicator with its value set to 'gumblar.cn' in your FortiSOAR instance:

Example of invoking a FortiSOAR playbook from Slack

This example explains how you can trigger the 'Enrich Playbook From Slack' playbook that is included in the "02 - Use Case - FortiSOAR for Slack" playbook collection and has already been enabled to be triggered from Slack using the 'Slash' commands:

The 'Enrich IP From Slack' playbook already has the default 'bot_enabled' tag, as well as the 'enrichIP' tag, which is the command that you will use to trigger this playbook. Also, this playbook has already set the current users' context. To get the current users' context, use vars.bot_context.user_id to get the current users' ID, or vars.bot_context.channel_id to get the ID of the Slack channel that has triggered the playbook. To run this playbook successfully, you must have configured threat intelligence connectors, which would analyze the submitted IP. In the case of this sample playbook, you must have the VirusTotal and IPStack connectors configured on your FortiSOAR instance. For the recommendations and requirements on how to create a playbook to be triggered from Slack, see the How to create a custom playbook that can be triggered from Slack topic.

To enrich an IP address from Slack, invoke the 'Enrich IP From Slack' playbook using the /fortisoar invokePlaybook <nameOfTagDefinedForCommand> <IPValue> or /fortisoar <nameOfTagDefinedForCommand> <IPValue> command. For example, type /fortisoar invokePlaybook enrichIP 1.1.1.1 or /fortisoar enrichIP 1.1.1.1 in the 'fortisoar-integration' channel. Since both the VirusTotal and IPStack connectors are configured, the indicator reputation summary from both VirusTotal and IPStack is displayed in the channel:

You can also execute configured actions directly from your configured Slack channel, i.e., 'fortisoar-integration'. For example, type an IP address, for example, 198.0.0.0, in the 'fortisoar-integration' channel. Click the More Actions option in that row, and click the action that you want to perform, for example, FSR > Enrich IP:

Once the command is run an acknowledgment is displayed, and since both the VirusTotal and IPStack connectors are configured, the indicator reputation summary from both VirusTotal and IPStack is displayed as a 'Thread' in the channel:

Example of running a Manual Input playbook that uses Slack as a delivery medium

To use 'Slack' as a channel for the delivery of manual input, you must create the playbook as defined in the 'Manual Input' topic of the "Triggers and Steps" chapter in the "Playbooks Guide" that is part of FortiSOAR Product Documentation. In brief, you need to keep the following in mind when designing a manual input step that delivers input prompts to users on Slack:

• In the 'Medium' section, select the Collect input from external users option, and choose Slack as the available channel. Next, choose whether you want to collect user responses by either sending a link to a page that contains the input form to the users (the Send input form link to users option) or by rendering the rich input form inline on the Slack channel for users to provide their inputs (the Send interactive input forms inline on external messaging app option).
  In the Provide Email Address(s) field, add the email address of the user from whom you want the response and who belongs to the same Slack workspace in which the FortiSOAR For Slack app is registered. Use the vars.bot_context.user_id, for the current users' ID, or vars.bot_context.channel_id for the ID of the Slack channel that has triggered the playbook.
• In the 'Input Prompt Design' section, design the input form that you want to present to Slack users by adding text and fields.
  Note: The 'File' and 'Email Template Field' fields are not supported in an input prompt. If you select any of these fields, then they are not displayed in the message displayed in Slack.
• In the 'Response Mapping' section, add the steps to be executed by the playbook once the users provide their response.

Once you have created the manual input playbook based on the required criteria, you can trigger the same in FortiSOAR.Once triggered, the playbook sends the input prompt to the Slack users based on the manual input step configuration.

• If the manual input step is designed with the Send input form link to users option, then in Apps > FortiSOAR > Messages tab, the respective Slack users will see a form with a link to the input form that contains the manual input. Clicking the input prompt link (Open input form in the following image) opens the form on a new page, where users can provide their responses and submit the form:
  
• If the manual input step is designed with the Send interactive input forms inline on external messaging apps option, then in Apps > FortiSOAR > Messages tab, then an interactive form is displayed to the respective Slack users, where they can provide their inputs and submit the form:
  

Once the form is submitted the manual input playbook resumes its execution based on user responses. You can see the progress of the Manual Input playbooks in the 'Executed Playbook Logs' in FortiSOAR:

The Executed Playbook Logs in FortiSOAR in the ENV of the Manual Input step contains the bot_context variable with a source parameter that contains the source (Slack) from which the playbook is triggered:

NOTE: Keep in mind that 'Manual Input' delivers the input form to users in Slack using the 'Send Manual Input/Approval Form to Slack' action of the Slack Connector. FortiSOAR uses the 'Send Manual Input/Approval Form to Slack' action to internally prepare the mapping code for the form object as expected by Slack and renders that form in Slack. If you want to send customized messages directly to Slack users, then you can use the 'Send Message' action of the Slack Connector, instead of using 'Manual Input'. For example, you can use the https://app.slack.com/block-kit-builder/ utility to create or get your own block code and then send beautifully formatted messages to Slack! Once you get your code block using the block kit builder, you can drop that code in the 'Blocks' field of the Send Message action.

How to create a custom playbook that can be triggered from Slack

To trigger a FortiSOAR playbook that can be triggered from Slack using a 'Slash' command, create the playbook keeping the following points in mind:

1. Add the default add 'bot_enabled' tag to the playbook.
2. Add a tag that represents the action performed by the playbook, when the user triggers the playbook. For example, if the playbook retrieves the reputation of the submitted domain name, then you can add a tag named 'getDomainRep'.
   This tag is used in the command used to trigger the playbook.
   Note: It is recommended to create unique tags so that appropriate playbooks get triggered. However, if the same tag is added to multiple playbooks, then the latest created playbook gets triggered.
3. It is recommended that the 'Start' step of such playbooks should be of type 'Referenced'.
4. There are two ways of passing inputs from Slack to FortiSOAR: Manual Input and Parameters.
   Manual Input: Has been described in the Example of running a Manual Input playbook that uses Slack as a delivery medium topic.
   Parameters: In the Playbook Designer, you can define a parameter using Tools > Edit Parameters, which displays the 'Parameters' dialog. In the Parameters dialog, click Add Parameter and enter the name of the parameter, for example, domainVal, that you can use in this playbook in, for example, a 'Set Variable' step.
   For example, if you type /fortisoar getDomainRep gumblar.cn in the 'fortisoar-integration' channel, then gumblar.cn will be mapped to the domainVal parameter.
   Note: Only one parameter can be passed with the command that triggers the playbook. Any string or value entered after a space is invalid. For example, if you enter /fortisoar enrichIP 1.1.1.1 www.somelink.com, then 'www.somelink.com' is invalid. Therefore, this method is recommended to be used only when you want to pass a single parameter. If you require to pass multiple parameters, use the 'Manual Input' step.
5. To get the current users' context, use the vars.bot_context.user_id, for the current users' ID, or vars.bot_context.channel_id for the ID of the Slack channel that has triggered the playbook. For example, you can refer to the sample playbooks included in "02 - Use Case - FortiSOAR for Slack" playbook collection, which is shipped with the FortiSOAR For Slack solution pack.
6. To send the response from FortiSOAR to Slack, use the 'Send Message' step of the Slack Connector. For more information, see the Slack Connector document on the FortiSOAR Connectors page.
   It is also recommended that you use a common variable, for example, bot_response to send all responses from FortiSOAR to Slack.

As an example, you can refer to the 'Enrich IP From Slack' playbook in the '02 - Use Case - FortiSOAR for Slack' playbook collection that is installed by default with the 'FortiSOAR For Slack' Solution Pack.

How to add a shortcut for a custom command

If you have built a playbook used to get domain reputation and you have added both bot_enabled and getDomainRep as tags to that playbook. Now, if you want getDomainRep as part of the shortcuts displayed in Slack, do the following:

1. Login to api.slack.com using your Slack account credentials.
2. From Your Apps select FortiSOAR For Slack.
3. From the menu, select Features > App Manifest.
4. In the 'App Manifest', scroll to the shortcuts section to view all the shortcuts added. Each shortcut contains its name, type i.e., whether its scope is 'global' or 'message', callback_id, and description:
   
5. Copy a shortcut, for example, 'enrichIP', and paste it into the shortcuts section, and edit it as per your requirement. For example to add getDomainRep as a shortcut, do the following:
   - name: FSR > Get Domain Reputation
type: message
callback_id: fsr_getDomainRep
description: Retrieves the reputation of the submitted domain name from FortiSOAR.
   Note: The callback_id must begin with 'fsr_' and then the tag that has been added in the FortiSOAR playbook to call this playbook, 'getDomainRep' in the case of our example.
6. Click Save Changes to save the changes to the App Manifest.
   Open Slack to view the added shortcut.

How to update your existing Slack application to use the bot-styled, bi-directional communication with Slack, using the FortiSOAR For Slack application

1. Login to api.slack.com using your Slack account credentials.
2. On the top bar, click Your apps > Create New App and select your existing app.
3. From the menu, select Features > App Manifest.
4. In the 'App Manifest', in the YAML tab, copy the contents for the following sections from the attached fortisoar_manifest.yml, and update them in your manifest.yml file:
   • display_information: This contains the name and description of the app. You can choose to retain the name and description of your app or change the name with the corresponding description to the "FortiSOAR For Slack" app.
   • features: This contains the features of the "FortiSOAR For Slack" along with the supported slash commands, shortcuts, etc. You can choose to replace the features of your app with the "FortiSOAR For Slack" app, or append the "FortiSOAR For Slack" features. If you append the features, then both your features and the "FortiSOAR For Slack" features should work.
   • oauth_config: This stores the permissions required for the app to work. It is recommended to append permissions rather than overwrite the existing permissions of your app.
   • settings: This contains the event_subscriptions of the app. It is recommended to append the event_subscriptions rather than overwrite the existing event_subscriptions of your app.
5. Click Save Changes to save the changes to the App Manifest.

fortisoar_manifest.zip

Logo_FortiSOAR for Slack application