Getting Started with Social Integrations - Nastel/gocypher-cybench-java GitHub Wiki

Quick Start Guide to Various Social Integrations

Introduction

CyBench offers the ability to integrate webhook endpoints from various communication software(s), such as Zoom. With a simple set-up, you will be able to have comparison results as well as notifications of anomalies sent directly into a chat channel of your choosing. When paired with other CyBench tools, such as the T2B Agent, you have the ability to run automated benchmarks and automated comparisons, while getting the results directly to your team's chat channel.

Zoom Quick Start on UI

NOTE: The CyBench UI also offers a quick guide when setting up Zoom integration.

Zoom Set-up

Requirements

  • CyBench Account (log-in via GitHub)
  • Zoom Account
    • Zoom Account Admin privileges if part of a team/company
    • NOTE: If you lack the required privileges, coordinate with your Zoom Account Manager
  • Zoom Incoming Webhook Endpoint (acquired during this guide)
  • Zoom Incoming Webhook Auth Token (acquired during this guide)

Preparation

  • Begin by navigating to the Incoming Webhook Bot on Zoom's App Marketplace, which can be found here.
  • Take note of the blue Add button, and click to add the bot
    • NOTE: If you lack the required privileges, you will instead only have the option to Request to Add, coordinate with your Zoom admin for this.

Obtaining the Endpoint and Auth Token

Once you've successfully added the Incoming Webhook Bot via Zoom's App Marketplace, you will now see the bot in the Chat sidebar, within the BOTS collapsible

  • Decide which chat channel you'd like the Zoom bot to relay messages to
    • NOTE: If you'd like to test, or prefer to keep notifications private, you can have messages sent to the Incoming Webhook bot's chat instead.
  • Once in the desired channel (or messaging the bot directly, to not have notifications post in a channel), type "/inc connect <ConnectionName>"
    • Example: /inc connect CyBenchConnection
    • <ConnectionName> is any value you decide, and is for organization purposes
    • Once you begin to type /inc, various possible commands will be suggested
  • The bot will immediately respond with a message containing the following information:
    • Channel - The channel selected to post notifications to
      • If you messaged the bot directly when running /inc connect, the channel will be the bot's chat itself, Incoming Webhook
    • Endpoint - A uniquely generated Endpoint URL, required by CyBench
    • Verification Token - A uniquely generated authorization token, only valid with the coinciding Endpoint, this token is required to authorize POST requests to Incoming Webhook, and should be kept both secret and safe. Also required by CyBench
    • Example curl - The bot also gives some example curl requests. Not necessary for CyBench, but good information to know
    • Link to Documentation - A link to the Incoming Webhook documentation provided by Zoom. Not necessary for the scope of this tutorial, but good information to know.

Example of message sent by Incoming Webhook, with sensitive information redacted

Integrating with CyBench

Once you've taken note of your unique Endpoint and Verification Token, navigate to the Workspace-Admin page on CyBench, by logging into CyBench, and then clicking on your name in the top right (where the log-in button was previously). You will be redirected to the My Profile tab.

  • Within this tab, under the Email/Notifications section, you will see the Integrations subsection
    • Click the blue camera (resembling the Zoom icon) to open the Zoom Integration settings pop-up
  • A prompt will open, requesting the Endpoint and Verification Token you generated before
  • Enter in that information, and click Apply
  • After a quick moment, a success message will display, and the dialog will close automatically.
  • Re-open the Zoom Integration settings pop-up, and click the green Test button
  • In whichever channel you set up for your connection, Incoming Webhook will send a test message
    • The message should read: "Zoom Webhook Test Message"
    • The CyBench UI will also display the response status from Zoom

Once integrated, the options to Test and Unlink become available

Post Set-up

  • Once integrated, comparison results will automatically be posted to the channel you set up Incoming Webhook in, as long as there are anomalies.
    • Comparisons that result in all passed/skipped (no anomalies) will not generate a message sent to Incoming Webhook
  • To stop receiving notifications from Incoming Webhook, you can open the Zoom Integration settings pop-up, from setup, and click the red Unlink button.

Example of comparison results message

Slack Set-up

Requirements

  • CyBench Account (log-in via GitHub)
  • Slack Account
    • Permission to add bots/integrations
    • Pre-existing Slack workspace
    • Pre-existing Slack channel for the bot to post notifications
    • NOTE: For companies or enterprises, the Slack Workspace Administrator may need to assist, for permissions purposes.

Integrating with CyBench

Integrating the CyBench Notifications bot to your workspace is done with a simple OAuth log-in.

  • Begin by navigating to the Workspace Admin page on CyBench, which is done by logging in with GitHub, and then clicking your name where the login button was previously after successful authentication.
  • You will be re-directed to the Workspace Admin page, specifically on the My Profile page. Take note of the Integrations section, where you can see icons for Slack as well as Zoom.
  • Click the yellow Slack icon.
  • The Slack Integration Settings dialog will pop up.
    • A few notes are detailed on this dialog regarding integration, as seen in the picture below.
  • Click the "Add to Slack" button
  • If you are not logged in to Slack, you will be prompted to login to the Workspace where you'd like the bot to be added
  • After ensuring you are in the correct Workspace, the CyBench Notifications bot will request permission into the Workspace (picture below)
  • You will also be prompted to designate the channel in which the bot will post to.
  • NOTE: Always be sure you're securely connected to Slack.com, you can verify this by checking the SSL certificate.
  • After clicking "Allow", the Integration process will begin, and after a short wait, you'll be re-directed back to the Workspace Admin page on CyBench.
    • At this point, you will now see the CyBench Notifications bot in your workspace.
  • Re-open the Slack Integration Settings dialog, you will now see the details regarding your integration. (picture below)
    • You will now also have the ability to send a test message, as well as unlink the bot.
  • Click the green "Test" button to send a test message to the channel you designated.
    • The Slack Endpoint response will appear in green text below the channel name, team/slack workspace name, etc. table.
    • The CyBench Notifications bot should post a message saying "Slack Webhook Test Message" (picture below)
  • To change the channel CyBench Notifications posts to, unlink the bot via the red "Unlink" button, and re-integrate into the different channel.
  • At this point, Slack integration is complete. Basic results of any comparison you run containing anomalies will post in the channel you designated. (picture below)
    • This includes all types of comparisons, ones manually ran on CyBench, automated comparisons you've set up, etc.
    • Comparisons with 0 anomalies will not post.

Telegram Integration

Requirements

  • CyBench Account (log-in via GitHub)
  • Telegram account
  • Access to create a bot, via the BotFather
  • Ability to add your created bot to a channel or group
  • Telegram Bot's Unique UserName (created during this guide)
  • Telegram Bot's Unique Auth Token (created during this guide)

Preparation

  • The first step to setting up Telegram's integration with Cybench is to message the BotFather to create a new bot.
    • With a chat open with BotFather, either type /newbot, or select the /newbot option from the blue 'Menu' button.
    • BotFather then prompts you for the name of your bot. This is a non-unique name and can be changed later on.
    • BotFather will then prompt you to choose the username of your bot.
      • This username must be unique.
      • This username can only be changed by messaging Telegram's Bot Support.
      • The username you choosemust end in bot, e.g. my_test_bot or NotificationTestBot
      • After creating the bot, take note of BotFather's response, which contains an Auth Token (redacted in example).
        • You will need this auth token, as well as the unique username of your bot for CyBench integration.
      • At this point, you have the ability to customize any feature of your bot, description, name, picture, etc.

Example of creating a bot

Integrating with CyBench

After taking note of your bot's unique username, as well as the generated Auth Token provided by BotFather, navigate to the Workspace-Admin page on CyBench, by logging into CyBench (via github), and clicking your name in the top right of the page (where the log-in button was previously), you will be redirected to the My Profile tab.

  • Within this tab, you will see the Email/Notifications section, containing an Integrations subsection
    • Click the Telegram icon (resembling a dark-blue paper airplane) to open the Telegram Integration settings pop-up
  • A prompt will open, requesting the username you chose and Auth Token you generated before.
  • Enter the requested information in the designated boxes, and click Apply.
  • After a moment, a success message will appear underneath the Wiki and Apply buttons.
    • The pop-up will then close automatically, and the page will refresh.
  • Re-open the Telegram Integration settings, and you'll see the webhook has been set, but some set-up is still required.
    • At this point, your bot's information is stored into XRAY, and a unique Webhook URL was generated and set with Telegram's backend.
    • In order to start receiving notifications, you must now add your Bot to a group/channel.

Example of Webhook set, but bot isn't added to any channels or groups.

  • Add your bot to a designated channel or group, depending on your environment
    • You may need Admin/Owner privileges to add group members
    • When adding your bot, you can search by either it's display name, or unique username

Adding the CyBNotificationBot to a group CyBenchGroup

  • After adding the bot to a group or channel, refresh the Workspace-Admin page, and re-enter the Telegram Integration settings menu.
    • You will now see the Channel/Group name the bot is currently in
    • You will also see the Chat ID of the channel/group
    • You have the ability to send a test message, to confirm integration.
      • Sending a test message should result in a 'Telegram Response OK!' message on CyBench
      • Your bot will post a message saying "Telegram Webhook Test Message"

Example of Telegram Integration fully set-up, with Test message success

At this point, you will now receive notifications of comparisons made (both automatic and manual) into the Group/Channel where your bot was added to. The bot is only able to post into one group/channel at a time, but can be removed/added freely, integration with CyBench will update automatically (i.e., you don't need to unlink/relink the bot every time you move the bot to a different group/channel).

Example of Telegram Integration comparison notification, along with test message

Teams Integration

Requirements

  • CyBench Account (log-in via GitHub)
  • Microsoft Teams account
    • Part of a Team with a Channel
    • Must have ability to add/modify Connectors in Channel
  • Unique Webhook link (generated during this guide)

Preparation

Assuming your Microsoft account is already set up with Teams, as well as being part of a Team, and having access to a channel (or multiple channels) to post to, the first step is to generate your unique webhook link. Begin by accessing the Connectors menu to configure the Incoming Webhook connector. To access the Connectors menu, select the team and channel you'd like, click the three dots (More options) button, adjacent to the Channel Info button in the top right. This will open a context menu, and if you have permissions, the Connectors option will be visible. Click on the Connectors option.

Once in the Connectors menu, search for the Incoming Webhook connector, and click add/configure

Once in the configuration screen for Incoming Webhook, there will be two configurable options. The first configuration is the name for your Incoming Webhook, this field is required, and will be the name of the "user" that posts CyBench notifications/messages. The second configuration is optional, and allows you to change the default image/avatar of the "user" that posts CyBench notifications/messages.

After choosing a name, and optionally changing the image, click "Create". Within a few moments, the configuration screen will update, and you will be provided with a unique, generated webhook URL, which should include the name of your team as a subdomain (e.g. https://myteamsname.webhook.office.com/...). You will need the full URL for CyBench. Click "Copy-to-Clipboard", and then click "Done". That is all the set-up required on the Teams application.

Example of configured Incoming Webhook connector

Integrating with CyBench

After taking note of the unique, generated webhook URL, navigate to the Workspace-Admin page on CyBench, done by logging into CyBench (via GitHub), and clicking your name in the rop right of the page (where the log-in button was previously), you will be redirected to the My Profile tab.

  • Within this tab, you will see the Email/Notifications section, containing an Integrations subsection
    • Click the Teams icon (resembling a purple trio) to open the MS Teams Integration settings pop-up
  • The Teams Integration Settings pop-up will open, requesting just one field, the generated webhook URL you received from setting up the Incoming Webhook connector
  • Enter the generated webhook URL, in full, into the "Webhook Link" field, any click Apply
  • After a few moments, a success message will appear underneath the Wiki and Apply buttons
    • The pop-up will then close automatically after a few seconds, and the page will refresh.
  • Re-open the Teams Integration Settings
    • Your unique URL will now encoded and displayed
    • You will now have the option to send a test message, via the green Test button
  • At the point, Teams integration with CyBench is complete
    • Any comparison you run containing anomalies will be reported to the Team and Channel you set the connector in.
    • At this time, only one Connector per CyBench account is allowed.

Example of set Teams Integration

Example of Teams Test Message

Example of Comparison Notification on Teams