> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/wazuh/wazuh-dashboard-plugins/llms.txt
> Use this file to discover all available pages before exploring further.

# External Integrations

> Integrate external APIs and services with Wazuh Dashboard for enhanced alerting, incident management, and threat intelligence

The Wazuh Dashboard supports integration with external platforms to extend security monitoring capabilities through automated alerting, incident management workflows, and threat intelligence enrichment.

## Overview

The dashboard provides integration support for:

* **Slack** - Team communication and real-time security notifications
* **PagerDuty** - Incident management and on-call alerting for critical events
* **Shuffle** - Security orchestration, automation, and response workflows
* **Maltiverse** - Threat intelligence enrichment and indicator of compromise analysis

Notification integrations leverage the OpenSearch Dashboards Notifications and Alerting plugins, while threat intelligence integrations are configured at the Wazuh manager level.

## Slack integration

Slack integration enables delivery of security alerts to designated Slack channels for team collaboration and rapid response.

### Prerequisites

* Slack workspace with administrative permissions
* Wazuh Dashboard with Notifications plugin enabled

### Configuration steps

#### 1. Create Slack incoming webhook

1. Navigate to [https://api.slack.com/apps](https://api.slack.com/apps)
2. Select **Create New App** > **From scratch**
3. Specify the application name (e.g., "Wazuh Security Alerts") and target workspace
4. Navigate to **Incoming Webhooks** in the application settings
5. Enable incoming webhooks
6. Select **Add New Webhook to Workspace**
7. Choose the destination channel (e.g., `#security-alerts`)
8. Copy the generated webhook URL in the format: `https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXX`

#### 2. Configure notification channel

1. Access the Wazuh Dashboard and navigate to **Menu > Explore > Notifications > Channels**
2. Select **Create channel**
3. Configure the channel parameters:
   * **Name**: `Slack Security Alerts`
   * **Type**: Select **Slack**
   * **Webhook URL**: Enter the webhook URL from step 1
   * **Description**: Optional description (e.g., "Security alerts to #security-alerts channel")
4. Select **Create**
5. Configure the channel state to **Unmuted** and **Enabled**

#### 3. Create alert monitor

1. Navigate to **Menu > Explore > Alerting > Monitors**
2. Select **Create monitor**
3. Configure monitor parameters:
   * **Monitor name**: `High Priority Security Events`
   * **Data source**: Select the Wazuh indices pattern
   * **Query**: Define alert conditions (e.g., `rule.level >= 12` for high-severity events)
   * **Trigger conditions**: Specify alerting thresholds
4. In the **Notifications** section:
   * Select the configured Slack channel
   * Customize the message template with alert metadata
5. Select **Create**

#### 4. Verify integration

1. Navigate to the Channels list and select the Slack channel
2. Select **Send test message**
3. Verify the test message appears in the designated Slack channel
4. Generate a test alert matching the monitor conditions
5. Confirm alert delivery to Slack

### Message customization

Customize alert messages using Mustache template syntax:

```
*Wazuh Security Alert*
*Severity*: {{ctx.trigger.severity}}
*Rule ID*: {{ctx.trigger.rule_id}}
*Description*: {{ctx.trigger.rule_description}}
*Agent*: {{ctx.trigger.agent_name}}
*Time*: {{ctx.trigger.timestamp}}
```

### Troubleshooting

* **Messages not delivered**: Verify webhook URL accuracy and application permissions
* **Channel muted**: Ensure channel status is set to Unmuted and Enabled
* **Monitor not triggering**: Validate query syntax and data source availability

## PagerDuty integration

PagerDuty integration enables automated incident creation and escalation for critical security events requiring immediate response.

### Prerequisites

* PagerDuty account with service configuration permissions
* Wazuh Dashboard with Notifications plugin enabled

### Configuration steps

#### 1. Create PagerDuty integration key

1. Access [https://app.pagerduty.com](https://app.pagerduty.com)
2. Navigate to **Services > Service Directory**
3. Select an existing service or create a new service
4. For new services, configure:
   * **Name**: `Wazuh Security Monitoring`
   * **Escalation Policy**: Select or create an escalation policy
   * **Integration Type**: Select **Events API v2**
5. Select **Add Service** or **Add Integration**
6. Copy the **Integration Key** (32-character identifier)

#### 2. Configure notification channel

1. Navigate to **Menu > Explore > Notifications > Channels**
2. Select **Create channel**
3. Configure channel parameters:
   * **Name**: `PagerDuty Critical Incidents`
   * **Type**: Select **PagerDuty**
   * **Integration Key**: Enter the integration key from step 1
   * **Description**: Optional description (e.g., "Critical security incidents to on-call team")
4. Select **Create**
5. Configure the channel state to **Unmuted** and **Enabled**

#### 3. Create incident monitor

1. Navigate to **Menu > Explore > Alerting > Monitors**
2. Select **Create monitor**
3. Configure for critical security events:
   * **Monitor name**: `Critical Security Incidents`
   * **Query**: `rule.level >= 14 OR rule.groups: "authentication_failed" OR rule.groups: "exploit_attempt"`
   * **Trigger conditions**: Immediate alerting for query matches
4. In the **Notifications** section:
   * Select the PagerDuty channel
   * Configure **Severity**: High or Critical
5. Select **Create**

#### 4. Test incident creation

1. Navigate to the Channels list and select the PagerDuty channel
2. Select **Send test message**
3. Access PagerDuty and verify test incident creation
4. Acknowledge and resolve the test incident

### Incident payload customization

Configure incident metadata:

* **Summary**: Alert title with key event identifiers
* **Severity**: Map Wazuh rule levels to PagerDuty severity classifications
* **Custom Details**: Include agent information, rule identifiers, and event descriptions
* **Deduplication Key**: Prevent duplicate incidents for identical events

### Troubleshooting

* **Incidents not created**: Verify integration key accuracy and service status
* **Duplicate incidents**: Configure appropriate deduplication keys
* **Incorrect escalation**: Update service settings in PagerDuty configuration

## Shuffle integration

Shuffle is a security orchestration platform that enables automated response workflows for security events.

### Prerequisites

* Shuffle account (cloud-hosted or self-hosted instance)
* Wazuh Dashboard with Notifications plugin enabled

### Configuration steps

#### 1. Create Shuffle webhook

1. Access [https://shuffler.io](https://shuffler.io) or your self-hosted Shuffle instance
2. Navigate to **Workflows**
3. Create a new workflow or select an existing workflow
4. Add a **Webhook** trigger node:
   * Select **Add Node** > **Trigger** > **Webhook**
   * Specify name: `Wazuh Security Events`
5. Copy the webhook URL in the format: `https://shuffler.io/api/v1/hooks/webhook_<id>`
6. Configure workflow actions (e.g., data enrichment, SIEM forwarding, ticket creation)

#### 2. Configure notification channel

1. Navigate to **Menu > Explore > Notifications > Channels**
2. Select **Create channel**
3. Configure channel parameters:
   * **Name**: `Shuffle Automation Workflow`
   * **Type**: Select **Webhook** (custom webhook URL)
   * **Webhook URL**: Enter the Shuffle webhook URL
   * **Method**: POST
   * **Headers**: Optional authentication headers if required
   * **Description**: Optional description (e.g., "Automated response workflows")
4. Select **Create**
5. Configure the channel state to **Unmuted** and **Enabled**

#### 3. Create automation monitor

1. Navigate to **Menu > Explore > Alerting > Monitors**
2. Select **Create monitor**
3. Configure for events requiring automation:
   * **Monitor name**: `Malware Detection Workflow`
   * **Query**: `rule.groups: "malware" OR rule.groups: "rootcheck"`
   * **Trigger conditions**: Match any qualifying event
4. In the **Notifications** section:
   * Select the Shuffle channel
   * Include relevant event metadata in payload
5. Select **Create**

#### 4. Validate integration

1. Navigate to the Channels list and select the Shuffle channel
2. Select **Send test message**
3. Access Shuffle and review workflow execution history
4. Verify webhook payload receipt
5. Validate workflow action execution

### Workflow examples

Common security automation workflows:

* **Malware response**: Endpoint isolation, forensic data collection, SOC notification
* **Brute force detection**: IP blocking, firewall rule updates, administrator alerts
* **Vulnerability detection**: Ticket creation, patching team assignment, remediation tracking
* **Compliance alerts**: GRC system logging, compliance officer notification

### Troubleshooting

* **Workflow not triggering**: Verify webhook URL accuracy and workflow active status
* **Payload format errors**: Ensure Shuffle expected schema matches notification payload structure
* **Authentication failures**: Verify webhook headers include required authentication tokens

## Maltiverse integration

Maltiverse provides threat intelligence enrichment and indicator of compromise analysis for security events.

### Prerequisites

* Maltiverse account with API access
* Wazuh manager with `ossec.conf` configuration access
* Root or sudo privileges on Wazuh manager host

### Configuration steps

#### 1. Generate Maltiverse API key

1. Access [https://maltiverse.com/](https://maltiverse.com/) and authenticate
2. Navigate to **Settings > API Keys** or **Account > API Access**
3. Select **Create API Key** or **Generate Key**
4. Specify a key name (e.g., "Wazuh Integration")
5. Copy the API key in the format: `mt-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`
6. Configure appropriate rate limits and permissions

#### 2. Configure Wazuh manager

1. Establish SSH connection to the Wazuh manager server

2. Edit the Wazuh manager configuration:

   ```bash theme={null}
   sudo nano /var/ossec/etc/ossec.conf
   ```

3. Add the Maltiverse integration configuration inside `<ossec_config>`:

   ```xml theme={null}
   <integration>
     <name>maltiverse</name>
     <api_key>mt-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx</api_key>
     <hook_url>https://api.maltiverse.com/v2</hook_url>
     <level>3</level>
     <alert_format>json</alert_format>
     <options>
       <file_sha1>yes</file_sha1>
       <file_md5>yes</file_md5>
       <ip_address>yes</ip_address>
       <hostname>yes</hostname>
       <url>yes</url>
     </options>
   </integration>
   ```

4. Configuration parameter descriptions:
   * **api\_key**: Maltiverse API authentication key
   * **level**: Minimum alert severity level for enrichment (default: 3)
   * **options**: Indicator types to enrich (file hashes, IP addresses, domains, URLs)

#### 3. Restart Wazuh manager

1. Restart the Wazuh manager service:

   **Systemd:**

   ```bash theme={null}
   sudo systemctl restart wazuh-manager
   ```

   **SysV init:**

   ```bash theme={null}
   sudo service wazuh-manager restart
   ```

2. Verify service status:

   ```bash theme={null}
   sudo systemctl status wazuh-manager
   ```

3. Validate integration initialization:

   ```bash theme={null}
   sudo tail -f /var/ossec/logs/ossec.log | grep -i maltiverse
   ```

   Expected output:

   ```
   INFO: Integration 'maltiverse' enabled
   ```

#### 4. Validate enriched alerts

1. Access the Wazuh Dashboard
2. Navigate to **Threat Hunting > Events** or **Security Events**
3. Locate alerts containing indicators of compromise (file hashes, IP addresses, domains)
4. Select an alert to view detailed metadata
5. Verify Maltiverse enrichment data:
   * **Threat classification**: malware, phishing, command and control
   * **Blacklist status**: Presence in threat intelligence feeds
   * **Historical data**: First observed and last observed timestamps
   * **Related campaigns**: Associated threat actors or attack campaigns

### Enrichment example

Example alert with Maltiverse enrichment:

```json theme={null}
{
  "rule": {
    "level": 12,
    "description": "Malicious file hash detected"
  },
  "data": {
    "file_sha1": "a1b2c3d4e5f6...",
    "maltiverse": {
      "classification": "malware",
      "type": "trojan",
      "blacklist": ["blocklist.de", "abuse.ch"],
      "score": 95,
      "first_seen": "2025-01-15T10:30:00Z"
    }
  }
}
```

### Troubleshooting

* **No enrichment data**: Verify API key validity and expiration status
* **Rate limit errors**: Review Maltiverse account limits and adjust alert level thresholds
* **Integration not loading**: Examine `ossec.log` for configuration errors
* **Invalid indicators**: Ensure alert data contains properly formatted indicators

### Rate limiting optimization

To mitigate rate limit issues:

* Configure `<level>` parameter to 7 or higher to enrich only medium and high severity alerts
* Limit enrichment to specific indicator types relevant to your environment
* Monitor API usage in the Maltiverse dashboard
* Consider implementing local indicator caching (future enhancement)

## Integration health monitoring

Monitor the operational status and performance of external integrations:

### Notification channel health

1. Navigate to **Menu > Explore > Notifications > Channels**
2. Verify all channels display **Enabled** and **Unmuted** status
3. Execute **Send test message** periodically to validate connectivity

### Monitor status

1. Navigate to **Menu > Explore > Alerting > Monitors**
2. Review monitor status for error states or failures
3. Examine trigger history for anomalies

### Integration logs

* **Wazuh manager**: `/var/ossec/logs/integrations.log`
* **OpenSearch Dashboards**: `/var/log/wazuh-dashboard/opensearch_dashboards.log`

### Performance metrics

* Alert delivery latency
* Failed notification attempt count
* API rate limit utilization (Maltiverse)

## Security best practices

### API key management

* Store API keys and credentials securely using secret management solutions
* Implement regular key rotation schedules
* Apply principle of least privilege to integration permissions

### Webhook security

* Maintain webhook URL confidentiality
* Require HTTPS for all webhook communications
* Validate webhook signatures where platform support exists

### Access control

* Restrict channel and monitor creation to authorized personnel
* Implement role-based access control for integration management
* Audit integration configuration changes

## Reliability best practices

### Testing

* Execute test messages weekly to verify integration functionality
* Configure alerts for failed notification attempts
* Maintain integration runbooks for troubleshooting

### Redundancy

* Configure multiple notification channels for critical alerts
* Implement fallback mechanisms for primary channel failures
* Distribute alerts across multiple communication platforms

## Performance best practices

### Alert volume management

* Balance alert visibility with notification noise
* Implement alert aggregation for high-volume events
* Configure appropriate severity thresholds

### Rate limit management

* Monitor API usage to prevent throttling
* Implement backoff strategies for rate-limited APIs
* Cache frequently accessed threat intelligence data

### Deduplication

* Configure deduplication keys to prevent duplicate notifications
* Implement alert suppression for recurring events
* Use time-based deduplication windows

## Related resources

* Notifications and Alerting module configuration
* Health Check module for integration monitoring
* External platform documentation:
  * Slack API: [https://api.slack.com/messaging/webhooks](https://api.slack.com/messaging/webhooks)
  * PagerDuty Events API: [https://developer.pagerduty.com/docs/ZG9jOjExMDI5NTgw-events-api-v2-overview](https://developer.pagerduty.com/docs/ZG9jOjExMDI5NTgw-events-api-v2-overview)
  * Shuffle: [https://shuffler.io/docs/workflows](https://shuffler.io/docs/workflows)
  * Maltiverse: [https://maltiverse.com/documentation](https://maltiverse.com/documentation)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.