Slack Destination Setup

Send detection alerts to Slack channels with rich formatted messages using Block Kit.

Prerequisites

• Slack workspace admin access
• Target channel(s) created

Setup Steps

1. Create Slack App

1. Go to https://api.slack.com/apps
2. Click Create New App → From scratch
3. Enter app name (e.g., "Security Detections")
4. Select your workspace
5. Click Create App

2. Add Bot Permissions

1. Navigate to OAuth & Permissions in the left sidebar
2. Scroll to Scopes section
3. Add the following Bot Token Scopes:

Required:

• chat:write - Send messages to channels
• chat:write.public - Send to public channels without joining

Optional:

• chat:write.customize - Use custom username and icon

3. Install App to Workspace

1. Scroll to top of OAuth & Permissions page
2. Click Install to Workspace
3. Review permissions
4. Click Allow
5. Copy the Bot User OAuth Token (starts with xoxb-)

Important: Save this token securely. You'll need it for configuration.

4. Get Channel ID

Method 1: From Channel Details

1. Right-click the channel name
2. Select View channel details
3. Scroll to bottom
4. Copy the Channel ID (e.g., C1234567890)

Method 2: From URL

1. Open the channel in Slack
2. Check the URL: https://app.slack.com/client/T12345678/C1234567890
3. The last part is the Channel ID

5. Invite Bot to Channel

In the Slack channel, type:

/invite @YourBotName

Replace YourBotName with your app's name.

Note: For public channels with chat:write.public scope, this step is optional.

6. Configure in Query.ai

Contact your Query.ai administrator to configure the Slack destination with:

Required Configuration:

• Bot User OAuth Token (stored securely)
• Channel ID or channel name

Optional Configuration:

• Custom username (default: "Security Detections")
• Custom icon emoji (default: ":shield:")
• Timeout in seconds (default: 30)

Message Format

Slack alerts include:

Header

• Severity emoji (🔴 CRITICAL, 🟠 HIGH, 🟡 MEDIUM, 🟢 LOW)
• Outcome emoji (✅ MATCHED, ❌ ERROR)
• Detection name

Details Section

• Outcome: MATCHED or ERROR
• Severity: Detection severity level
• Matches: Number of matching events
• Detection ID: Configuration ID
• Run Type: SCHEDULED or MANUAL
• Threshold: Operator and value (e.g., "GREATER_THAN 5")
• Eagerness: EAGER or EXHAUSTIVE

Description

Full detection description text

Timestamps

• Ran At: When detection executed
• Time Range: Query time window
• Exhaustiveness: COMPLETED or STOPPED_EARLY (if available)
• Search ID: FSQL API identifier (if available)
• Trace ID: AWS X-Ray trace ID (if available)

Errors

List of error messages (if any)

Action Button

"View in Query.ai" button linking to replay

Color Bar

Left sidebar color based on severity:

• Red: CRITICAL
• Orange: HIGH
• Yellow: MEDIUM
• Green: LOW

Testing

Test Bot Token

Test your bot token with curl:

curl -X POST https://slack.com/api/chat.postMessage \
  -H "Authorization: Bearer xoxb-your-token-here" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "C1234567890",
    "text": "Test message from Security Detections",
    "blocks": [
      {
        "type": "section",
        "text": {
          "type": "mrkdwn",
          "text": "Test message :rocket:"
        }
      }
    ]
  }'

Expected Response:

{
  "ok": true,
  "channel": "C1234567890",
  "ts": "1234567890.123456",
  "message": {...}
}

Test with Detection

1. Create a test detection with low threshold
2. Add Slack destination
3. Click Run Now
4. Check Slack channel for message

Troubleshooting

Common Issues

Verify Bot Permissions

1. Go to https://api.slack.com/apps
2. Select your app
3. Navigate to OAuth & Permissions
4. Verify scopes are present
5. If scopes changed, reinstall app to workspace

Check Bot Installation

1. In Slack, go to Apps in left sidebar
2. Find your bot app
3. Verify it shows as installed
4. Check which channels it's in

Multiple Channels

To send alerts to different channels, create separate destinations:

Example Use Cases:

• Critical alerts → #security-critical
• All alerts → #security-all
• Team-specific → #soc-team

Each destination can use:

• Same bot token, different channels
• Different bot tokens for different workspaces
• Different usernames/icons for identification

Configuration Options

Required

bot_token (secret)

• Bot User OAuth Token from Slack app
• Starts with xoxb-
• Stored securely in AWS Secrets Manager

channel

• Channel ID (e.g., C1234567890) or name (e.g., #alerts)
• Channel ID is preferred for reliability

Optional

username

• Custom display name for bot
• Default: "Security Detections"
• Requires chat:write.customize scope

icon_emoji

• Custom emoji icon for bot
• Default: ":shield:"
• Format: :emoji_name:
• Requires chat:write.customize scope

thread_ts

• Parent message timestamp for thread replies
• Use to reply in existing thread
• Format: "1234567890.123456"

reply_broadcast

• Broadcast thread reply to channel
• Default: false
• Only applies when thread_ts is set

timeout

• Request timeout in seconds
• Default: 30
• Increase if experiencing timeouts

Advanced Features

Threading

To reply to an existing message thread, provide the parent message timestamp:

Use Case: Group related alerts in a single thread

Configuration: Set thread_ts to parent message timestamp

Custom Branding

Customize bot appearance per destination:

SOC Team:

• Username: "SOC Alerts"
• Icon: ":rotating_light:"

Compliance Team:

• Username: "Compliance Monitor"
• Icon: ":clipboard:"

Security Best Practices

1. Never Commit Tokens: Always store tokens in Secrets Manager
2. Use Least Privilege: Only grant required scopes
3. Rotate Tokens: Rotate bot tokens every 90 days
4. Monitor Usage: Review bot activity in Slack audit logs
5. Restrict Channels: Only invite bot to necessary channels
6. Use Channel IDs: Prefer Channel IDs over names for reliability

Token Rotation

To rotate bot token:

1. Go to https://api.slack.com/apps
2. Select your app
3. Navigate to OAuth & Permissions
4. Click Revoke on old token
5. Click Reinstall to Workspace
6. Copy new token
7. Update token in Query.ai configuration
8. Test with a manual detection run

Resources

• Slack API Documentation
• chat.postMessage API
• Block Kit Builder - Design custom message layouts
• OAuth Scopes - Complete scope reference
• Slack App Management - Manage your apps