mbeje/wazuh-shuffle-jira-soc-automation
GitHub: mbeje/wazuh-shuffle-jira-soc-automation
该项目实现了一条完整的 SOC 自动化流水线，通过 Wazuh 检测安全事件、Shuffle 编排自动化逻辑、Jira 自动创建工单，消除了告警分诊中的手动操作瓶颈。
Stars: 0 | Forks: 0
# Wazuh-Shuffle-Jira SOC 自动化
实时 SIEM 检测 → SOAR 自动化 → 自动创建工单。这是一个已部署且正常运行的告警分类流水线，端到端连接了 Wazuh、Shuffle 和 Jira。
这是一个自动化安全告警分类流水线，它通过 **Wazuh (SIEM)** 检测安全事件，通过 **Shuffle (SOAR)** 进行处理，并自动在 **Jira** 中创建可追踪的工单——复现了真实安全运营中心 (SOC) 中使用的核心“从告警到案件”工作流。
## 概述
手动进行告警分类是 SOC 中最大的瓶颈之一——在开始实际调查之前，分析师仅将告警从检测工具转移到工单系统就需要花费大量时间。本项目将这一首要步骤进行了端到端的自动化：
**检测 → 富化/路由 → 创建案件**，配置完成后无需任何人工干预。
*Wazuh 仪表板显示了按严重程度划分的检测到的告警。*
## 架构
*Shuffle SOAR 工作流：传入的 Wazuh 告警 (Webhook) → 创建 Jira 工单，并配置了身份验证。*
```
┌─────────────┐ ┌──────────────┐ ┌─────────────┐
│ Wazuh │ alert │ Shuffle │ create │ Jira │
│ (SIEM) │ ─────► │ (SOAR) │ issue │ (Ticketing) │
│ Ubuntu VM │webhook │ Cloud SaaS │ ─────► │ Cloud SaaS │
└─────────────┘ └──────────────┘ └─────────────┘
```
- **Wazuh** —— 自托管的 SIEM（VirtualBox/Ubuntu 虚拟机），通过其内置的本地 agent 监控主机活动，应用检测规则，并将发现映射到 MITRE ATT&CK 技术。
- **Shuffle** —— 云托管的 SOAR 平台。通过 webhook 接收告警，并执行创建 Jira 工单的自动化逻辑。
- **Jira** —— 云托管的工单/案件管理系统，接收带有告警上下文（agent、规则 ID、严重程度）的结构化工单。
## 功能说明
1. Wazuh 使用其默认规则集监控系统活动（身份验证尝试、PAM 会话、syslog、AppArmor 事件等）。
2. 当告警在达到或超过配置的严重级别时触发，自定义的 Wazuh 集成脚本会将告警（以 JSON 格式）发送到 Shuffle 的 webhook。
3. Shuffle 的工作流接收告警，并通过 Jira REST API v3 创建相应的 Jira issue，并使用真实的告警数据（agent 名称、规则 ID、严重级别）填充摘要和描述。
4. 工单进入 Jira 面板，准备好供分析师审查——整个链条无需人工干预自动运行。
## 示例：触发的检测
使用模拟的 SSH 暴力破解尝试（重复登录失败）来验证该流水线：
- Wazuh 检测到多次身份验证失败，并自动将它们映射到 MITRE ATT&CK 技术：**Password Guessing**、**Brute Force**、**Valid Accounts**、**SSH**。
- 每个符合条件的告警都被转发到 Shuffle，并实时创建了单独的 Jira 工单，在检测和工单创建之间没有任何手动步骤。
*检测到 42 次身份验证失败，并自动映射到 MITRE ATT&CK 技术（Password Guessing、Brute Force、Valid Accounts、SSH）。*
**在自动化运行之前——Jira 中只有默认的示例工单：**
**SSH 暴力破解测试之后——自动创建了新工单，未采取任何手动操作：**
## 技术栈
| 组件 | 角色 | 托管方式 |
|---|---|---|
| Wazuh 4.9 | SIEM / 检测引擎 | 自托管 (VirtualBox, Ubuntu 24.04) |
| Shuffle | SOAR / 自动化与编排 | 云端 |
| Jira Cloud | 工单/案件管理 | 云端 |
| Python 3 | 自定义 Wazuh 集成脚本 | 在 Wazuh manager 内运行 |
## 设置说明
### 1. Wazuh (SIEM)
- 部署在 Ubuntu 24.04 LTS 虚拟机 上，通过 Wazuh 的 all-in-one 安装脚本（manager + indexer + dashboard）进行安装。
- Manager 内置的本地 agent (`000`) 监控主机本身——对于单节点实验室环境，无需单独安装 agent。
### 2. Wazuh → Shuffle 集成
自定义集成脚本 (`/var/ossec/integrations/custom-shuffle`) 将符合条件的告警转发到 Shuffle 的 webhook：
```
#!/usr/bin/env python3
import sys, json, requests
def main(args):
try:
alert_file = args[1]
webhook_url = args[3]
with open(alert_file) as f:
alert_json = json.load(f)
response = requests.post(webhook_url, json=alert_json,
headers={"Content-Type": "application/json"}, timeout=10)
print(f"Status code: {response.status_code}")
except Exception as e:
print(f"ERROR: {e}")
if __name__ == "__main__":
main(sys.argv)
```
在 `ossec.conf` 中注册：
```
custom-shuffle
YOUR_SHUFFLE_WEBHOOK_URL
3
json
```
### 3. Shuffle (SOAR)
- 工作流：`Webhook → Jira (Create Issue)`
- Jira 节点通过 Atlassian API token 进行身份验证（而不是账户密码——Jira Cloud 的 API 需要在 `id.atlassian.com/manage-profile/security/api-tokens` 生成的 token）。
- 请求体在描述字段使用 Atlassian Document Format (ADF)，这是 Jira 的 REST API v3 所要求的：
```
{
"fields": {
"project": { "key": "KAN" },
"summary": "Wazuh Alert: $exec.rule.description",
"issuetype": { "name": "Task" },
"description": {
"type": "doc",
"version": 1,
"content": [
{
"type": "paragraph",
"content": [
{
"type": "text",
"text": "Alert triggered on agent $exec.agent.name | Rule ID $exec.rule.id | Level $exec.rule.level"
}
]
}
]
}
}
}
```
### 4. Jira (工单管理)
- 免费层级的 Jira Cloud 项目（看板模板）。
- 工单会自动创建，其中的标题、agent 名称、规则 ID 和严重程度均直接从实时告警中提取。
## 挑战与修复
在构建过程中解决的真实部署阻力：
- **ISO/虚拟机启动失败** —— Ubuntu ISO 下载损坏；通过重新下载并在挂载前验证文件完整性得以解决。
- **Wazuh 服务启动超时** —— 在资源受限的虚拟机上，indexer 的 JVM 超过了 systemd 的默认启动超时时间；通过覆盖 `TimeoutStartSec` 修复。
- **`ossec.conf` 中的 XML 无效** —— 一个集成块被放置在 `` 根标签之外，破坏了配置解析器；通过纠正元素嵌套修复。
- **静默集成失败** —— Wazuh 的 `custom-shuffle` 脚本失败且没有可见错误；添加了显式的异常处理和状态码记录，以暴露真正的失败原因（处于未激活状态的 Shuffle webhook）。
- **Jira 400 错误** —— 通过三个层面查明根本原因：(1) Shuffle 存储的身份验证中的 API URL 格式错误，(2) 使用了 Atlassian 账户密码而不是 API token，(3) 当 Jira Cloud 的 v3 API 要求使用 Atlassian Document Format (ADF) 时，发送了纯字符串格式的 `description` 字段。
*真实的调试历史记录——在实现可正常工作、可重复的流水线之前，对 Jira 身份验证和 payload 格式进行的迭代修复。*
## 展示的技能
- SIEM 部署与管理 (Wazuh)
- SOAR 工作流设计与自动化 (Shuffle)
- REST API 集成与身份验证 (Jira Cloud API v3)
- Linux 系统管理（VirtualBox、Ubuntu、systemd 故障排查）
- 用于安全工具集成的 Python 脚本编写
- 基于 MITRE ATT&CK 的检测解读
- 跨多服务、多云流水线的根本原因调试
## 免责声明
这是一个个人实验室/作品集项目，旨在用于学习和演示目的。上述配置示例中显示的凭据、webhook URL 和 API token 已被替换为占位符，并非实时环境中使用的实际值。