<!-- Copyright (c) 2026 defconxt. All rights reserved. -->
<!-- Licensed under AGPL-3.0 — see LICENSE file for details. -->
---
name: building-security-chatops-integration
description: >-
  Build security ChatOps integrations with Slack and PagerDuty for alert
  notification, interactive incident response, SOC command execution,
  and escalation routing with audit logging.
domain: cybersecurity
subdomain: security-operations-automation
tags:
  - chatops
  - slack
  - pagerduty
  - notifications
  - incident-response
  - bot
version: "1.0"
author: defconxt
license: AGPL-3.0
metadata:
  mitre-attack: []
---

# Building Security ChatOps Integration

## Overview

Security ChatOps brings SOC operations into team communication platforms.
Operators receive contextual alerts, execute response actions via slash
commands, and maintain audit trails of all ChatOps interactions. This
reduces context-switching and accelerates incident response.

Mode: `[MODE: BLUE]` — Operational communication automation.

## Prerequisites

| Requirement | Details |
|---|---|
| Python 3.10+ with `slack_sdk`, `requests` | Required |
| Slack workspace with bot token (xoxb-) and signing secret | Required |
| PagerDuty API key for escalation integration | Required |
| Webhook endpoint for SIEM alert forwarding | Required |

## Key Concepts

### Slack Alert Formatting

```python
def format_security_alert(alert: dict) -> dict:
    """Format alert as Slack Block Kit message."""
    severity_emoji = {"critical": "🔴", "high": "🟠", "medium": "🟡", "low": "🟢"}
    emoji = severity_emoji.get(alert.get("severity", "low"), "⚪")

    return {
        "blocks": [
            {"type": "header", "text": {"type": "plain_text", "text": f"{emoji} {alert['title']}"}},
            {"type": "section", "fields": [
                {"type": "mrkdwn", "text": f"*Severity:* {alert['severity']}"},
                {"type": "mrkdwn", "text": f"*Source:* {alert['source']}"},
                {"type": "mrkdwn", "text": f"*Host:* {alert.get('hostname', 'N/A')}"},
                {"type": "mrkdwn", "text": f"*Time:* {alert.get('timestamp', 'now')}"},
            ]},
            {"type": "actions", "elements": [
                {"type": "button", "text": {"type": "plain_text", "text": "Acknowledge"}, "action_id": "ack_alert", "style": "primary"},
                {"type": "button", "text": {"type": "plain_text", "text": "Escalate"}, "action_id": "escalate_alert", "style": "danger"},
            ]},
        ]
    }
```

### Command Handler

```python
COMMANDS = {
    "/soc-status": "Show current SOC queue and open incidents",
    "/investigate": "Start investigation on an alert — /investigate ALT-001",
    "/isolate": "Isolate a host — /isolate workstation-42",
    "/escalate": "Escalate to on-call — /escalate INC-001 tier2",
}
```

## Workflow

### Step 1: Send Alert Notification

```bash
node scripts/agent.js --action send-alert --channel "#soc-alerts" --severity critical
```

### Step 2: Process Command

```bash
node scripts/agent.js --action handle-command --command "/investigate ALT-001"
```

### Step 3: Escalate Incident

```bash
node scripts/agent.js --action escalate --incident INC-001 --tier 2
```

## Verification

- [ ] Alerts display with correct severity formatting and action buttons
- [ ] Slash commands execute with proper authorization checks
- [ ] Escalation triggers PagerDuty on-call notification
- [ ] All ChatOps actions logged with user, timestamp, and action

## References

- [Slack Block Kit Builder](https://app.slack.com/block-kit-builder)
- [Slack Bolt for Python](https://slack.dev/bolt-python/concepts)
- [PagerDuty Events API v2](https://developer.pagerduty.com/api-reference/)
