Merge pull request #23 from splunk-soar-connectors/next

Merging next to main for release 2.6.0

.github/workflows/generate-doc.yml

@@ -0,0 +1,14 @@
+name: Generate Readme Doc
+on:
+  workflow_dispatch:
+  push:
+    paths:
+      - '*.json'
+      - 'readme.html'
+jobs:
+  generate-doc:
+    runs-on: ubuntu-latest
+    steps:
+     - uses: 'phantomcyber/dev-cicd-tools/github-actions/generate-doc@main'
+       with:
+         GITHUB_TOKEN: ${{ secrets.SOAR_APPS_TOKEN }}

.pre-commit-config.yaml

@@ -1,6 +1,6 @@
 repos:
 -   repo: https://github.com/phantomcyber/dev-cicd-tools
-    rev: v1.13
+    rev: v1.16
     hooks:
     -   id: org-hook
     -   id: package-app-dependencies

LICENSE

@@ -186,7 +186,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright (c) 2016-2022 Splunk Inc.
+   Copyright (c) 2016-2023 Splunk Inc.
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

__init__.py

@@ -1,6 +1,6 @@
 # File: __init__.py
 #
-# Copyright (c) 2016-2022 Splunk Inc.
+# Copyright (c) 2016-2023 Splunk Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

readme.html

@@ -1,5 +1,5 @@
 <!-- File: readme.html
-  Copyright (c) 2016-2022 Splunk Inc.
+  Copyright (c) 2016-2023 Splunk Inc.
 
   Licensed under Apache 2.0 (https://www.apache.org/licenses/LICENSE-2.0.txt)
 -->
@@ -35,7 +35,130 @@ <h2>Authentication</h2>
 <p>
   SOAR's Slack App needs a bot token to read messages from and post messages to slack channels. The app also needs a
   verification token to verify POST requests received from Slack.
-<h3>Create a Slack App</h3>
+<h3>Steps for Creating a Slack App Using App Manifest File (Recommended)</h3>
+App manifest file in (.yaml):
+<br><br>
+Use below manifest file for creating slack app.
+<br><br>
+<pre>
+  display_information:
+  name: soarbot
+features:
+  bot_user:
+    display_name: soarbot
+    always_online: false
+oauth_config:
+  scopes:
+    user:
+      - channels:write
+      - groups:write
+      - im:write
+      - mpim:write
+      - channels:read
+      - groups:read
+      - im:read
+      - mpim:read
+      - users:read
+      - chat:write
+      - reactions:write
+      - files:write
+    bot:
+      - channels:manage
+      - groups:write
+      - im:write
+      - mpim:read
+      - mpim:write
+      - channels:read
+      - groups:read
+      - im:read
+      - users:read
+      - chat:write
+      - reactions:write
+      - files:write
+      - chat:write.public
+      - app_mentions:read
+      - channels:history
+      - im:history
+settings:
+  event_subscriptions:
+    bot_events:
+      - app_mention
+      - message.channels
+      - message.im
+  interactivity:
+    is_enabled: true
+  org_deploy_enabled: false
+  socket_mode_enabled: true
+  token_rotation_enabled: false
+</pre>
+<br><br>
+Select <b> From an app manifest </b> option.
+<br><br>
+<a href="/app_resource/slack_3ac26c7f-baa4-4583-86ff-5aac82778a86/img/slack_select_from_app_manifest.png">
+  <img src="/app_resource/slack_3ac26c7f-baa4-4583-86ff-5aac82778a86/img/slack_select_from_app_manifest.png">
+</a>
+<br><br>
+Select a workspace.
+<br><br>
+<a href="/app_resource/slack_3ac26c7f-baa4-4583-86ff-5aac82778a86/img/slack_select_workspace.png">
+      <img src="/app_resource/slack_3ac26c7f-baa4-4583-86ff-5aac82778a86/img/slack_select_workspace.png">
+</a>
+<br><br>
+Paste above manifest file in <b>yaml</b> section.
+<br><br>
+<a href="/app_resource/slack_3ac26c7f-baa4-4583-86ff-5aac82778a86/img/slack_enter_app_manifest.png">
+      <img src="/app_resource/slack_3ac26c7f-baa4-4583-86ff-5aac82778a86/img/slack_enter_app_manifest.png">
+</a>
+<br><br>
+Click <b>Next</b>, then verify all scopes for Bot and User which is added from the manifest file.
+<br><br>
+<a href="/app_resource/slack_3ac26c7f-baa4-4583-86ff-5aac82778a86/img/slack_review_summary_oauth.png">
+      <img src="/app_resource/slack_3ac26c7f-baa4-4583-86ff-5aac82778a86/img/slack_review_summary_oauth.png">
+</a>
+<br><br>
+Note that event subscriptions from the manifest file will also be added for the bot. Proceed by clicking <b>Create</b>.
+<br><br>
+<a href="/app_resource/slack_3ac26c7f-baa4-4583-86ff-5aac82778a86/img/slack_review_summary_settings.png">
+      <img src="/app_resource/slack_3ac26c7f-baa4-4583-86ff-5aac82778a86/img/slack_review_summary_settings.png">
+</a>
+<br><br>
+On the next page, there is a <b>Verification Token</b>. This token is needed during asset configuration.
+<br><br>
+<a href="/app_resource/slack_3ac26c7f-baa4-4583-86ff-5aac82778a86/img/slack_basic_info.png">
+  <img src="/app_resource/slack_3ac26c7f-baa4-4583-86ff-5aac82778a86/img/slack_basic_info.png">
+</a>
+<br><br>
+On the same page, there is an <b>App Level tokens</b> section. Click on the <b>Generate Token and Scope</b>
+button. You will then be prompted to provide a token name, for example, <b>socket_token</b>. Just below this is the
+<b>Add Scope</b> button. Add <b>connection:write & authorization:read</b> and click on <b>Generate</b>. This token is
+needed during asset configuration.
+<br><br>
+<a href="/app_resource/slack_3ac26c7f-baa4-4583-86ff-5aac82778a86/img/slack_socket_token.png">
+  <img src="/app_resource/slack_3ac26c7f-baa4-4583-86ff-5aac82778a86/img/slack_socket_token.png">
+</a>
+<br><br>
+On the same page under the <b>Install your app</b> section, click <b>Install to Workspace</b>.
+<br><br>
+<a href="/app_resource/slack_3ac26c7f-baa4-4583-86ff-5aac82778a86/img/slack_install_app_manifest.png">
+  <img src="/app_resource/slack_3ac26c7f-baa4-4583-86ff-5aac82778a86/img/slack_install_app_manifest.png">
+</a>
+<br><br>
+On the next page, click <b>Allow</b>.
+<br><br>
+<a href="/app_resource/slack_3ac26c7f-baa4-4583-86ff-5aac82778a86/img/slack_allow_app_manifest.png">
+  <img src="/app_resource/slack_3ac26c7f-baa4-4583-86ff-5aac82778a86/img/slack_allow_app_manifest.png">
+</a>
+<br><br>
+After authorizing the app, in the menu bar on the left, select <b>OAuth & Permissions</b>. The <b>Bot User OAuth Token
+</b> and <b>User OAuth Token</b> are required during asset configuration.
+<br><br>
+<a href="/app_resource/slack_3ac26c7f-baa4-4583-86ff-5aac82778a86/img/slack_auth_tokens.png">
+  <img src="/app_resource/slack_3ac26c7f-baa4-4583-86ff-5aac82778a86/img/slack_auth_tokens.png">
+</a>
+<br><br>
+On the same page, scroll down to the <b>Scopes</b> section and verify the scopes for Bot and User added from the manifest file.
+<br><br>
+<h3>Steps for Creating a Slack App From Scratch</h3>
 Creating a Slack App is required to get the proper bot token for authenticating the SOAR Slack App. To do this, go to <a
   href="https://api.slack.com/apps">https://api.slack.com/apps</a> in a browser, and select <b>Create New App</b>.
 <br><br>
@@ -51,17 +174,17 @@ <h3>Create a Slack App</h3>
 </a>
 
 <br><br>
-On the next page, there is a <b>Verification Token</b>. This token will be needed during asset configuration.
+On the next page, there is a <b>Verification Token</b>. This token is needed during asset configuration.
 <br><br>
 <a href="/app_resource/slack_3ac26c7f-baa4-4583-86ff-5aac82778a86/img/slack_basic_info.png">
   <img src="/app_resource/slack_3ac26c7f-baa4-4583-86ff-5aac82778a86/img/slack_basic_info.png">
 </a>
 
 <br><br>
-On the same page, there is a <b>App Level tokens</b>. This dialog box will have a <b>Generate Token and Scope</b>
-button, click on it. It would again open an pop up, give token name <b>socket_token</b>. Just below this would be the
-<b>Add Scope</b> button, add <b>connection:write & authorization:read</b> and click on <b>Generate</b>. This token will
-be needed during asset configuration.
+On the same page, there is an <b>App Level tokens</b> section. Click on the <b>Generate Token and Scope</b>
+button. You will then be prompted to provide a token name, for example, <b>socket_token</b>. Just below this is the
+<b>Add Scope</b> button. Add <b>connection:write & authorization:read</b> and click on <b>Generate</b>. This token is
+needed during asset configuration.
 <br><br>
 <a href="/app_resource/slack_3ac26c7f-baa4-4583-86ff-5aac82778a86/img/slack_socket_token.png">
   <img src="/app_resource/slack_3ac26c7f-baa4-4583-86ff-5aac82778a86/img/slack_socket_token.png">
@@ -156,8 +279,6 @@ <h3>Create a Slack App</h3>
     </td>
     <td>
       <li>chat:write</li>
-      <li>chat:write:user</li>
-      <li>chat:write:bot</li>
     </td>
   </tr>
   <tr>
@@ -176,23 +297,20 @@ <h3>Create a Slack App</h3>
     </td>
     <td>
       <li>files:write</li>
-      <li>files:write:user</li>
     </td>
   </tr>
   <tr>
     <td>Ask Question/Ask Question Channel</td>
     <td>
       <li>chat:write</li>
+      <li>chat:write.public</li>
     </td>
     <td>
       <li>chat:write</li>
-      <li>chat:write.public</li>
-      <li>chat:write:user</li>
-      <li>chat:write:bot</li>
     </td>
   </tr>
 </table>
-
+NOTE: <b>chat:write</b> replaces both <b>chat:write:user</b> and <b>chat:write:bot</b> and <b>files:write</b> replaces both <b>files:write:user</b> and <b>files:write:bot</b>
 <br><br>
 Next, click on <b>Install App</b> in the side bar. On that page, click <b>Install to Workspace</b>.
 <br><br>
@@ -206,8 +324,8 @@ <h3>Create a Slack App</h3>
   <img src="/app_resource/slack_3ac26c7f-baa4-4583-86ff-5aac82778a86/img/slack_allow_app.png">
 </a>
 <br><br>
-After authorizing the app, the next window will show the app's authorization tokens. The <b>Bot User OAuth Access
-  Token</b> and <b>OAuth Access Token</b> will be required during asset configuration.
+After authorizing the app, in the menu bar on the left, select <b>OAuth & Permissions</b>. The <b>Bot User OAuth Token
+</b> and <b>User OAuth Token</b> are required during asset configuration.
 <br><br>
 <a href="/app_resource/slack_3ac26c7f-baa4-4583-86ff-5aac82778a86/img/slack_auth_tokens.png">
   <img src="/app_resource/slack_3ac26c7f-baa4-4583-86ff-5aac82778a86/img/slack_auth_tokens.png">
@@ -219,14 +337,19 @@ <h2>SOAR Base URL</h2>
 <a href="/app_resource/slack_3ac26c7f-baa4-4583-86ff-5aac82778a86/img/slack_system_settings.png">
   <img src="/app_resource/slack_3ac26c7f-baa4-4583-86ff-5aac82778a86/img/slack_system_settings.png">
 </a>
+<br><br>
+NOTE: If the PORT is other than 443, please add the port in the <b>BASE URL For Splunk SOAR</b> field.
+<br><br>
+<a href="/app_resource/slack_3ac26c7f-baa4-4583-86ff-5aac82778a86/img/slack_system_settings_with_port.png">
+  <img src="/app_resource/slack_3ac26c7f-baa4-4583-86ff-5aac82778a86/img/slack_system_settings_with_port.png">
 <h2>SOAR Slack Asset</h2>
 Fill out the required values in the <b>Asset Definition</b> tab.
 <br><br>
 <a href="/app_resource/slack_3ac26c7f-baa4-4583-86ff-5aac82778a86/img/slack_asset_info.png">
   <img src="/app_resource/slack_3ac26c7f-baa4-4583-86ff-5aac82778a86/img/slack_asset_info.png">
 </a>
 <br><br>
-Fill out the <b>Bot User OAuth Access Token</b>, <b>OAuth Access Token</b>,<b>Socket Token</b> and <b>Verification
+Fill out the <b>Bot User OAuth Token</b>, <b>User OAuth Token</b>,<b>Socket Token</b> and <b>Verification
   Token</b> in the <b>Asset Settings</b> tab. Optionally specify permissions and authorized Member IDs if you intend to
 use SlackBot features. Also, anytime you update the any of the tokens mentioned above, please stop the bot once and
 restart the on poll to reflect the latest changes.
@@ -334,6 +457,12 @@ <h2>Set up Socket Mode in Slack</h2>
       <img src="/app_resource/slack_3ac26c7f-baa4-4583-86ff-5aac82778a86/img/slack_subscription_events.png">
     </a>
     <br><br>
+    Note: When socket mode is enabled, click on <b>Interactivity & Shortcuts</b> on the left menu bar and verify that the <b>Request URL</b> field is empty in the <b>Interactivity</b> section.
+    <br><br>
+    <a href="/app_resource/slack_3ac26c7f-baa4-4583-86ff-5aac82778a86/img/slack_interactivity_without_requesturl.png">
+      <img src="/app_resource/slack_3ac26c7f-baa4-4583-86ff-5aac82778a86/img/slack_interactivity_without_requesturl.png">
+    </a>
+    <br><br>
     <h2>Slack Bot</h2>
     <h3>Ingest Settings</h3>
     To run the SOAR SlackBot that will get SOAR to take commands from Slack, ingestion needs to be enabled on the SOAR

release_notes/2.6.0.md

@@ -0,0 +1,3 @@
+* Updated summary for 'ask question' action [PAPP-29263]
+* Updated documentation [PAPP-29259, PAPP-29325]
+* Added documentation for create slack app using 'app manifest' option