Slack triage¶
Connect a Slack app in your organization's workspace to receive SheerSight alerts and incidents, and classify individual alerts with emoji reactions.
Slack is an alert destination, separate from the tools that supply security events. Connecting it does not start a source collector or give you a feed of Slack audit logs.
Before you start¶
| You need | Why |
|---|---|
| A dedicated instance that is enrolled and online | It receives the encrypted configuration and connects to Slack. |
| A connected security source | The app posts detections from your sources. A quiet source may produce no alerts. |
| Permission to create and install a Slack app in the target workspace | Your workspace may require an owner or app manager to approve installation. |
| An alert channel in that same workspace | Invite the bot there; restrict membership to people trusted to triage security alerts. |
| A tenant admin or Sheer Safe operator with a configured authenticator | Connection changes require permission and authenticator verification. |
Who can manage the connection
Customer admins can manage their organization's Slack connection. Analysts and viewers see connection status only; ask your admin to make changes. Sheer Safe operators can also manage the customer connection. If you need help, request Slack through Integrate → Request an integration. Do not put tokens in requests or email.
Use one app for each customer's workspace. The bot token, app-level token and channel must belong to the same app and workspace. This customer destination is separate from any internal operator Slack channel configured by Sheer Safe.
What the app can do¶
| Permission | Token | Purpose |
|---|---|---|
chat:write |
Bot token | Post alert and incident messages as the app. |
reactions:read |
Bot token | Receive reaction events in conversations the app has joined. |
connections:write |
App-level token | Open the outbound Socket Mode connection used for events. |
These are the permissions used by this integration. The bot can write messages, so the read-only credential instructions for source collectors do not apply to it. Invite the bot only to the channels where you want it to work.
Socket Mode delivers events over a WebSocket opened by your instance. You do not need a public Request URL or an inbound endpoint. See Slack's Socket Mode guide and the permission references.
1. Create the Slack app¶
Open Your Slack apps, select Create New App → From an app manifest, and select the workspace that owns your alert channel. Choose YAML, replace the example with the following manifest, review the permissions, then create the app.
display_information:
name: SheerSight Triage
description: Posts SheerSight detections and reads emoji reactions as triage dispositions.
features:
bot_user:
display_name: SheerSight Triage
always_online: false
oauth_config:
scopes:
bot:
- chat:write
- reactions:read
settings:
event_subscriptions:
bot_events:
- reaction_added
interactivity:
is_enabled: false
org_deploy_enabled: false
socket_mode_enabled: true
token_rotation_enabled: false
The manifest configures the bot, scopes, reaction subscription and Socket Mode. It does not generate the two tokens. Continue with steps 2 and 3.
Leave automatic token rotation disabled for this integration: it currently accepts static tokens, rather than refreshing expiring tokens. Rotate credentials manually using the procedure below.
Create the app manually instead
If you already created an app from scratch, configure it to match the manifest:
- In OAuth & Permissions → Scopes → Bot Token Scopes, add
chat:writeandreactions:read. - In Settings → Socket Mode, turn on Enable Socket Mode.
- In Event Subscriptions, enable events and add
reaction_addedunder Subscribe to bot events. With Socket Mode enabled, a Request URL is not needed. - Leave Interactivity & Shortcuts disabled and automatic token rotation off.
- Generate an app-level token and install the app as described below.
If you change OAuth scopes after installation, reinstall the app to apply them.
2. Generate the app-level token¶
- Open the app's Basic Information page.
- Under App-Level Tokens, select Generate Token and Scopes.
- Give the token a name, such as
sheersight-socket. - Add
connections:write, then generate the token. - Save the token securely. It starts with
xapp-and belongs in the console's App-level token field.
This is different from the bot token. Do not use the app's signing secret, client secret or app ID in either token field.
3. Install the app and copy the bot token¶
- Open Install App, or OAuth & Permissions → Install to Workspace.
- Approve installation in the same workspace selected in step 1. If approval is required, have the workspace owner or app manager complete it.
- Copy the Bot User OAuth Token. It starts with
xoxb-and belongs in the console's Bot token field.
Save both tokens in your approved credential store. The console clears the fields after a successful relay and does not show the tokens again.
4. Invite the bot and get the channel ID¶
- Open the chosen alert channel in Slack.
- Invite the app, for example with
/invite @SheerSight Triage. Select the app if Slack asks you to choose between matching names. You can also add it through the channel's integrations. - Open the channel details by selecting its name. Copy Channel ID, normally in About.
Use an ID such as
C0123456789; some older private channels have an ID starting withG.
Use the ID rather than #security-alerts, a channel URL, or a workspace ID. A renamed channel keeps
its ID. The bot must be invited even if the channel is public; invite it explicitly to a private
channel too.
5. Enable Slack triage in SheerSight¶
These steps are for a customer admin or Sheer Safe operator:
- Sign in to the console and select the correct organization.
- Open Integrate and find Slack. Customer admins select Change connection to open the token fields. Operators use Slack triage app. Management requires an enrolled instance with its encryption key available.
-
Fill in all three values:
Console field Paste Bot token (xoxb-…) The Bot User OAuth Token from step 3. App-level token (xapp-…, connections:write) The app-level token from step 2. Alert channel ID The ID from step 4. -
Enter your current Authenticator code when needed. Set up the authenticator under Settings → Profile if you have not done so. The code is from your authenticator app, not the email PIN used to sign in. A successful verification covers step-up actions for the next 10 minutes in the same signed-in session; during that window the field can be left empty. A temporary authenticator lock still prevents changes.
- Select Update Slack connection or Enable Slack triage, as shown by the form.
The tokens are encrypted in your browser to the dedicated instance's key. The console relays ciphertext; the instance decrypts and applies it locally. Sheer Safe operates the instance and can access its configuration when maintaining it. See Security & trust.
A successful relay message means the console accepted the configuration. It does not mean Slack has accepted the tokens or that an alert has reached your channel.
6. Verify delivery and reactions¶
Check these stages separately:
- Relay: in Relayed credentials, the entry moves from pending to applied. This shows the instance consumed the configuration; also check its reported health.
- Slack health: the customer panel shows Slack is connected and the operator panel shows Slack triage on after token checks or a successful post. It can take a few instance polls and a console refresh for the report to arrive.
- Message delivery: confirm a new, genuine detection reaches the chosen channel from SheerSight Triage. No alert is guaranteed immediately on a quiet source, and ordinary manual chat messages do not create detections. If needed, arrange an approved lab test with Sheer Safe.
- Reaction processing: on an individual alert posted by the bot, add the emoji that accurately describes the alert. Refresh Alerts after the instance reports again and confirm the disposition. Incident summaries, late-event digests and older webhook messages are not individual bot alerts for this check.
The health badge validates token checks or a successful post; it does not prove the entire reaction path works. Check a message and its disposition before relying on the integration.
Health labels¶
The customer summary card shows connected, not connected, needs attention, or status unavailable. While an admin is changing or disconnecting the integration, the panel uses the detailed labels below, as does the operator panel. A relayed change remains waiting until an instance report confirms the outcome; unknown or stale reports do not confirm completion.
| Label | Meaning and next step |
|---|---|
| not reported | No Slack health report has arrived. Check that the instance is online and reporting. |
| record mode | Bot-based Slack triage is disabled. Monitoring continues; see the fallback section. |
| Slack triage on | Token checks or a post succeeded. Verify delivery to the expected channel and reaction processing. |
| Slack triage failing | Slack rejected authentication or posting, or the configuration was invalid. Read the error and use the troubleshooting table. |
| report stale | The last report is too old to establish current health. Check instance connectivity and refresh. |
activating means the reported state has not yet resolved to a recognized health label. A report is marked stale after two minutes without an update; after 24 hours without a retained report, the panel can return to not reported.
Failed posting does not automatically restore the webhook
In Slack mode, direct source alert delivery has been removed. If posting fails, affected alerts may not reach Slack or the console Alerts page until posting succeeds. The loop retries real-time detections without advancing their cursor, but recovery of scheduled detections whose aggregation window passes is not guaranteed. Source collection is separate from this delivery failure. Fix the integration promptly; if that is not possible, have an operator Switch back to record mode, or have a customer admin use Disconnect Slack. Verify the configured webhook route and console reporting.
Emoji dispositions¶
| Emoji | Slack name | Meaning |
|---|---|---|
| ✅ | white_check_mark |
True positive: a real threat or detection requiring attention. |
| 🔕 | no_bell |
False positive: incorrect or noisy detection. Counts toward learned suppression. |
| 🌱 | seedling |
Benign: expected activity, recorded without contributing to suppression. |
Other emoji do not classify an alert. Classification applies to individual alert messages tracked by the triage loop, not arbitrary messages, webhook alerts, incident summaries or late-event digests. Removing a reaction does not undo the disposition: the integration subscribes to added reactions only. Adding it again records another disposition, even on the same alert; do not remove and re-add reactions as a test. Slack users are not checked against console roles, and reactions are recorded as a generic operator action rather than attributed to the individual Slack user. Restrict channel membership to trusted reviewers and do not invite the bot to unrelated channels. Ask Sheer Safe if a classification needs correction.
Reactions affect monitoring
Do not label a real alert false positive just to test the app. False-positive feedback contributes to suppression once the learning conditions are met. A true-positive reaction can disable a matching active suppression, and recorded true-positive feedback prevents learning suppression for that pattern while the feedback remains in the learning window. Use accurately classified alerts or an agreed lab test.
Record mode and switching back¶
Without the Slack app, the triage loop records alerts and incidents for the console, but does not consume emoji reactions. On instances with an alert webhook configured, the instance's direct alert delivery uses that webhook. Record mode is not the same as disabling monitoring.
With Slack triage enabled, the triage loop owns alert delivery and the instance removes the corresponding direct source alerts for connected sources. During a mode transition, an alert can be delivered twice while the two paths hand over. A failed batch that is retried can also repeat messages that were posted before the failure.
Customer admins select Disconnect Slack, read the confirmation, and supply an authenticator code if the 10-minute window has expired. Operators use Switch back to record mode in their panel. Both return the customer integration to record mode. The instance clears the three Slack app settings and restores direct alert delivery for connected sources. Verify record mode, continued console reporting, and webhook delivery if configured.
This does not uninstall the app or revoke its tokens in Slack. If you are retiring the integration, verify the fallback route first, then revoke the credentials or uninstall the app in Slack.
Rotate a token or change the channel¶
The steps depend on what is changing:
- App-level token: in Basic Information → App-Level Tokens, generate another token with
connections:write. Relay it with the current bot token and channel ID, verify delivery and reactions, then revoke the old app-level token. - Bot token: simply reinstalling is not a reliable way to rotate a static token. Plan the change with your Slack administrator and Sheer Safe. Establish and verify record-mode fallback first, then revoke the old authorization and reinstall the app in the same workspace. Copy the current Bot User OAuth Token, verify bot channel membership, and relay the full configuration to enable Slack triage again. This can interrupt delivery if fallback is unavailable. Slack documents the revocation/reinstallation behavior in its token guide.
- Channel: invite the existing bot to the new channel and copy its ID; no new token is needed.
For every change:
- Coordinate with the Slack administrator and your tenant admin or Sheer Safe operator.
- Generate the replacement credential in the same app, or invite the bot to the new channel and copy its ID.
- In Change connection (customer) or Slack triage app (operator), submit the full set: bot token, app-level token and channel ID. Even if only one value changed, all three are required by this form.
- Verify the relay, health, actual message delivery and reactions again.
- For the app-level token, revoke the old token after replacement delivery is verified. For the bot token, follow the revoke-first and reinstall procedure above; do not assume that old and new static bot credentials can overlap.
Clearing only one field is not a disconnect procedure. Use Disconnect Slack (customer) or Switch back to record mode (operator) to disable bot-based triage safely.
Troubleshooting¶
| Symptom or error | What to check |
|---|---|
| You cannot see Slack management controls | Only tenant admins and operators can manage the connection, and the instance must be enrolled. Analysts and viewers see status only. Ask Sheer Safe if your admin controls are unavailable. |
| Enable or Update button is disabled | The instance's encryption key has not loaded or could not be fetched. Check enrollment, connectivity and the page error. |
| Token or channel validation error | Use xoxb- for the bot token, xapp- for the app-level token and a C… or G… channel ID. Paste single-line tokens without quotes. |
authenticator_required |
Set up your authenticator in Settings → Profile. |
stepup_required or an expired verification window |
Enter a fresh authenticator code and retry. The email sign-in PIN does not satisfy this check. |
| Wrong/replayed code, or rate limit after code failures | Wait for a new code; repeated failures can temporarily lock verification. Check authenticator clock synchronization rather than repeatedly submitting the same code. |
| Relay stays pending | The instance must be online and able to poll the console. Check connectivity before submitting again. |
| Relay is applied, but stays in record mode | Ask Sheer Safe to check instance reconciliation. If starting the Slack process failed, the instance may have restored direct alerts; relay acknowledgement alone does not confirm a mode change. |
| Relay is applied, but Slack is failing | Applied configuration is not Slack verification. Read the panel error and verify both tokens, scopes, workspace and channel. |
invalid_auth, token_revoked or account_inactive |
Check token type and installation in the intended workspace. Replace revoked credentials, then submit the complete set. |
missing_scope |
Bot needs chat:write and reactions:read; app token needs connections:write. Reinstall after bot scope changes and relay the current tokens. |
not_in_channel |
Invite the bot to the channel whose ID you submitted. |
channel_not_found |
Check the channel ID, workspace and bot membership, particularly for a private channel. |
| Messages arrive but reactions do not | Check Socket Mode is on, reaction_added is subscribed, and the app-level token has connections:write. React to a tracked individual bot alert with a listed emoji, then allow reporting time. |
| Slack triage on, but no messages | Verify a source is collecting and a new detection actually occurred. Authentication alone does not prove the channel ID is correct. |
| report stale or posts stop | Check the instance's outbound access to Slack HTTPS and Socket Mode WebSockets, and ask Sheer Safe to inspect health. |
| Duplicate alerts | A brief overlap can occur during mode handover. A retry after a partly failed batch can also repeat posts. Persistent duplicates need investigation by Sheer Safe. |
For unresolved issues, contact support with the organization, approximate time and health label. Operators can include a sanitized error code; customer admins receive a fixed status and should ask Sheer Safe for the specific diagnostic. Do not include tokens, authenticator codes, or screenshots that expose them.
Slack references¶
- App manifest reference
- Socket Mode setup
- Bot message permission: chat:write
- Reaction permission: reactions:read
- App-level connection permission: connections:write
- reaction_added event