Skip to content

Latest commit

 

History

History
127 lines (108 loc) · 4.23 KB

File metadata and controls

127 lines (108 loc) · 4.23 KB

Session Directions: Add Slack Bot Mode Support

Context

The Socket Python CLI currently supports Slack notifications via incoming webhooks. We need to add an alternative "bot" mode that uses a Slack App with Bot Token for more flexible channel routing.

Current Implementation

  • File: socketsecurity/plugins/slack.py
  • File: socketsecurity/config.py
  • Env var: SOCKET_SLACK_CONFIG_JSON
  • Current config uses url and url_configs for webhook routing

Requirements

1. Add Mode Selection

  • Add top-level mode field to Slack config
  • Valid values: "webhook" (default), "bot"
  • Mode determines which authentication and routing method to use

2. Webhook Mode (existing, default)

{
  "enabled": true,
  "mode": "webhook",
  "url": ["https://hooks.slack.com/..."],
  "url_configs": {
    "webhook_0": {"repos": ["repo1"], "severities": ["critical"]}
  }
}

Keep all existing webhook functionality unchanged.

3. Bot Mode (new)

{
  "enabled": true,
  "mode": "bot",
  "bot_configs": [
    {
      "name": "critical_alerts",
      "channels": ["security-alerts", "critical-incidents"],
      "repos": ["prod-app"],
      "severities": ["critical"],
      "reachability_alerts_only": true
    },
    {
      "name": "all_alerts", 
      "channels": ["dev-alerts"],
      "severities": ["high", "medium"]
    }
  ]
}
  • New env var: SOCKET_SLACK_BOT_TOKEN (Bot User OAuth Token starting with xoxb-)
  • Use bot_configs array instead of url + url_configs
  • Each bot_config has:
    • name: identifier for logging
    • channels: array of Slack channel names or IDs to post to
    • All existing filter options: repos, severities, alert_types, reachability_alerts_only, always_send_reachability

4. Channel Routing

  • Slack API accepts both channel names (without #) and channel IDs (C1234567890)
  • Recommend supporting both: try name first, fallback to ID if needed
  • API endpoint: https://slack.com/api/chat.postMessage
  • Request format:
{
    "channel": "channel-name",  # or "C1234567890"
    "blocks": blocks
}
  • Headers: {"Authorization": f"Bearer {bot_token}", "Content-Type": "application/json"}

5. Implementation Tasks

config.py

  • No changes needed (config is loaded from JSON env var)

slack.py

  1. Update send() method:

    • Check self.config.get("mode", "webhook")
    • If "webhook": call existing _send_webhook_alerts() (refactor current logic)
    • If "bot": call new _send_bot_alerts()
  2. Create _send_bot_alerts() method:

    • Get bot token from env: os.getenv("SOCKET_SLACK_BOT_TOKEN")
    • Validate token exists and starts with "xoxb-"
    • Get bot_configs from config
    • For each bot_config, filter alerts same way as webhooks
    • For each channel in bot_config's channels array, post message via chat.postMessage API
  3. Create _post_to_slack_api() helper method:

  4. Error handling:

    • Log if bot token missing when mode is "bot"
    • Handle API errors (invalid channel, missing permissions, rate limits)
    • Parse Slack API response JSON (it returns 200 with error in body)
  5. Reuse existing:

    • All filtering logic (_filter_alerts)
    • All block building (create_slack_blocks_from_diff, _create_reachability_slack_blocks_from_structured)
    • All reachability data loading

6. Testing Considerations

  • Test both modes don't interfere with each other
  • Test channel name resolution
  • Test channel ID usage
  • Test multiple channels per bot_config
  • Test error handling when bot token invalid or missing
  • Verify block count limits still respected (50 blocks)

7. Documentation Updates (README.md)

Add bot mode configuration examples and SOCKET_SLACK_BOT_TOKEN env var documentation.

Key Files to Modify

  1. socketsecurity/plugins/slack.py - main implementation
  2. README.md - add bot mode documentation

Notes

  • Slack chat.postMessage returns HTTP 200 even on errors. Check response JSON for "ok": false
  • Rate limit: 1 message per second per channel (more generous than webhooks)
  • Channel names are case-insensitive, don't need # prefix
  • Public and private channels both work if bot is invited