Hnnno/Incident-Response-Playbook-Automator
GitHub: Hnnno/Incident-Response-Playbook-Automator
基于MITRE ATT&CK框架的自动化安全事件响应编排系统，通过YAML剧本将告警自动映射并执行封禁、通知、取证等响应动作链。
Stars: 0 | Forks: 0
# IR Playbook Automator
自动化安全事件响应系统。接收警报，将其映射到与 **MITRE ATT&CK** 框架对齐的 YAML 格式 playbook 中，并自动执行一系列操作：IP 封锁、通知、创建工单以及收集取证证据。
## 目录
- [描述](#descripcion)
- [架构](#arquitectura)
- [支持的警报类型](#tipos-de-alerta-soportados)
- [要求](#requisitos)
- [安装说明](#instalacion)
- [使用说明](#uso)
- [项目结构](#estructura-del-proyecto)
- [警报格式](#formato-de-alerta)
- [添加新 playbook](#agregar-un-nuevo-playbook)
- [添加新操作](#agregar-una-nueva-accion)
- [生产环境配置](#configuracion-para-produccion)
- [测试](#tests)
- [路线图](#roadmap)
## 描述
```
Alerta ingresada → Playbook identificado → Acciones ejecutadas → Reporte guardado
| | | |
JSON / dict playbooks.yaml bloquear_ip JSON + log
(MITRE TTP) enviar_email Evidencia JSON
crear_ticket Audit trail
```
系统默认以 **模拟模式** 运行，这意味着在明确启用之前，不会对系统执行任何实际操作。这允许您在没有风险的情况下迭代和测试 playbook。
## 架构
```
ir-playbook-automator/
├── config/
│ ├── playbooks.yaml # Definicion declarativa de playbooks (MITRE-mapeados)
│ └── configuracion.yaml # SMTP, ticketing, firewall, modo simulacion
├── src/
│ ├── principal.py # Punto de entrada CLI
│ ├── modelos_alerta.py # Dataclasses: Alerta, ResultadoAccion, ReporteEjecucion
│ ├── parser_alertas.py # Ingesta desde archivo JSON o dict
│ ├── motor_playbook.py # Motor de ejecucion paso a paso
│ └── acciones/
│ └── __init__.py # bloquear_ip, aislar_host, deshabilitar_cuenta,
│ # enviar_notificacion, crear_ticket, registrar_evidencia
├── alertas/
│ └── alertas_muestra.json # Alertas de ejemplo para demo y pruebas
├── tests/
│ └── test_playbook.py # 15 tests unitarios (pytest)
├── logs/
│ ├── evidencia/ # Archivos JSON de evidencia por incidente
│ └── reportes/ # Reportes completos de ejecucion de playbook
└── requirements.txt
```
## 支持的警报类型
| 警报类型 | MITRE TTP | 严重性 | 执行的操作 |
|-------------------------|-----------|-----------|--------------------------------------------------------|
| `fuerza_bruta` | T1110 | 高 | 封锁 IP → 邮件 → 工单 → 证据 |
| `malware_detectado` | T1204 | 严重 | 隔离主机 → 邮件 → 工单 → 证据 |
| `escalada_privilegios` | T1068 | 严重 | 禁用账户 → 邮件 → 工单 → 证据 |
| `exfiltracion_datos` | T1048 | 严重 | 封锁 IP (24小时) → 邮件 → 工单 → 证据 |
| `escaneo_puertos` | T1046 | 中 | 封锁 IP (30分钟) → 邮件 → 工单 |
## 要求
- Python 3.11 或更高版本
- `requirements.txt` 中列出的依赖项
```
pyyaml>=6.0
requests>=2.31.0
pytest>=7.4.0
pytest-cov>=4.1.0
```
## 安装说明
```
git clone https://github.com/tu-usuario/ir-playbook-automator
cd ir-playbook-automator
pip install -r requirements.txt
```
## 使用说明
**使用示例警报运行（模拟模式）：**
```
cd src
python principal.py
```
**使用自定义警报文件运行：**
```
python principal.py --archivo-alertas ../alertas/alertas_muestra.json
```
**指定报告目录：**
```
python principal.py --archivo-alertas ../alertas/alertas_muestra.json --directorio-reportes ../reportes/
```
**执行实际操作（需要完整配置）：**
```
python principal.py --sin-simulacion
```
**预期输出：**
```
=================================================================
RESUMEN DE EJECUCION - IR PLAYBOOK AUTOMATOR
=================================================================
Total alertas procesadas : 5
Playbooks exitosos : 5
Playbooks con errores : 0
-----------------------------------------------------------------
[ALTA ] fuerza_bruta | Ataque de Fuerza Bruta Detec | OK
[MEDIA ] escaneo_puertos | Escaneo de Puertos Detectado | OK
[CRITICA] escalada_privilegios | Intento de Escalada de Privi | OK
[CRITICA] exfiltracion_datos | Posible Exfiltracion de Dato | OK
[CRITICA] malware_detectado | Malware o Archivo Sospechoso | OK
=================================================================
```
## 项目结构
### `modelos_alerta.py`
定义了系统的主要 dataclass：
- `TipoAlerta` — 包含支持的事件类型的枚举
- `Severidad` — 包含严重级别的枚举：`baja`（低）、`media`（中）、`alta`（高）、`critica`（严重）
- `Alerta` — 核心模型，包含源 IP、用户、主机、详细信息以及自动生成的 ID
- `ResultadoAccion` — playbook 每个步骤的单个结果
- `ReporteEjecucion` — 包含元数据、结果和最终状态的完整执行报告
### `parser_alertas.py`
将来自不同来源的警报标准化为 `Alerta` 对象：
- `desde_dict(datos)` — 解析原始字典
- `desde_archivo_json(ruta)` — 读取并解析 JSON 文件（列表或单个警报）
- `desde_json_string(cadena)` — 从 JSON 字符串解析
- `obtener_alertas_muestra()` — 生成演示警报而无需文件
### `motor_playbook.py`
从 YAML 加载 playbook 并按顺序执行每个步骤。对于每个警报：
1. 查找与 `tipo_alerta` 对应的 playbook
2. 遍历定义的步骤
3. 从 `REGISTRO_ACCIONES` 解析操作函数
4. 将 `ResultadoAccion` 累积到 `ReporteEjecucion` 中
5. 使用时间戳和全局状态完成报告
### `acciones/__init__.py`
包含所有可用的响应函数和 `REGISTRO_ACCIONES`：
| 操作 | 描述 |
|-----------------------|----------------------------------------------------------|
| `bloquear_ip` | 通过 iptables 封锁源 IP（或模拟封锁） |
| `aislar_host` | 切断受影响主机的网络连接 |
| `deshabilitar_cuenta` | 禁用受损的用户账户 |
| `enviar_notificacion` | 通过 SMTP 向 SOC 团队发送电子邮件 |
| `crear_ticket` | 在 Jira 或模拟系统中创建事件工单 |
| `registrar_evidencia` | 将取证证据保存为 JSON 文件 |
## 警报格式
警报定义为包含以下字段的 JSON 对象：
```
{
"tipo_alerta": "fuerza_bruta",
"ip_origen": "45.33.32.156",
"severidad": "alta",
"usuario_objetivo": "administrador",
"host_objetivo": "srv-dc-01",
"timestamp": "2024-11-15T14:32:00",
"detalles": {
"intentos_fallidos": 87,
"ventana_tiempo_segundos": 45,
"protocolo": "RDP",
"puerto": 3389
}
}
```
必填字段：`tipo_alerta`、`ip_origen`。
可选字段：`severidad`（默认值：`media`）、`timestamp`（默认值：当前时间）、`usuario_objetivo`、`host_objetivo`、`detalles`。
## 添加新 playbook
编辑 `config/playbooks.yaml` 并在 `playbooks:` 下添加新键：
```
playbooks:
acceso_no_autorizado:
nombre: "Acceso No Autorizado Detectado"
descripcion: "Intento de acceso fuera de horario o desde ubicacion inusual"
severidad: alta
mitre_ttp: "T1078"
pasos:
- accion: bloquear_ip
parametros:
duracion_minutos: 120
razon: "Acceso no autorizado detectado"
- accion: enviar_notificacion
parametros:
asunto: "[ALERTA] Acceso no autorizado"
prioridad: alta
- accion: crear_ticket
parametros:
titulo: "Acceso No Autorizado - IP Bloqueada"
categoria: "acceso_indebido"
asignado: "equipo-iam"
- accion: registrar_evidencia
parametros:
recolectar: ["ip_origen", "usuario_objetivo", "hora_acceso"]
```
无需修改 Python 代码。引擎会通过 `tipo_alerta` 键自动加载 playbook。
## 添加新操作
在 `src/acciones/__init__.py` 中定义函数并注册它：
```
def mi_accion_personalizada(alerta: Alerta, parametros: dict, configuracion: dict) -> ResultadoAccion:
simulacion = configuracion.get("general", {}).get("simulacion", True)
# logica de la accion
mensaje = f"[SIMULACION] Accion ejecutada sobre {alerta.ip_origen}"
return ResultadoAccion("mi_accion_personalizada", True, mensaje, simulacion=simulacion)
REGISTRO_ACCIONES["mi_accion_personalizada"] = mi_accion_personalizada
```
然后可以在任何 playbook 中通过 `accion: mi_accion_personalizada` 引用它。
## 生产环境配置
### 电子邮件通知
配置环境变量：
```
export EMAIL_CONTRASENA="contrasena-smtp"
```
编辑 `config/configuracion.yaml`：
```
general:
simulacion: false
notificaciones:
email:
servidor_smtp: "smtp.gmail.com"
puerto_smtp: 587
remitente: "alertas-soc@tudominio.com"
destinatarios:
- "equipo-soc@tudominio.com"
- "gerente-seguridad@tudominio.com"
```
### 与 Jira 集成
```
export JIRA_USUARIO="tu-usuario"
export JIRA_TOKEN_API="tu-token-api"
```
```
tickets:
sistema: "jira"
modo_simulado: false
jira:
url: "https://tuempresa.atlassian.net"
clave_proyecto: "SOC"
tipo_incidencia: "Incidente"
```
### 使用 iptables 的真实防火墙 (Linux)
```
firewall:
sistema: "iptables"
modo_simulado: false
iptables:
cadena: "INPUT"
requiere_sudo: true
```
## 测试
```
pytest tests/ -v
```
```
tests/test_playbook.py::TestModelosAlerta::test_generacion_id_alerta PASSED
tests/test_playbook.py::TestModelosAlerta::test_alerta_a_dict PASSED
tests/test_playbook.py::TestModelosAlerta::test_resultado_accion_exitoso PASSED
tests/test_playbook.py::TestModelosAlerta::test_resultado_accion_fallido PASSED
tests/test_playbook.py::TestModelosAlerta::test_reporte_todo_exitoso PASSED
tests/test_playbook.py::TestModelosAlerta::test_reporte_con_fallos PASSED
tests/test_playbook.py::TestParserAlertas::test_parseo_dict_valido PASSED
tests/test_playbook.py::TestParserAlertas::test_tipo_desconocido PASSED
tests/test_playbook.py::TestParserAlertas::test_alertas_muestra_no_vacias PASSED
tests/test_playbook.py::TestParserAlertas::test_alertas_muestra_campos_requeridos PASSED
tests/test_playbook.py::TestAcciones::test_bloquear_ip_simulacion PASSED
tests/test_playbook.py::TestAcciones::test_enviar_notificacion_simulacion PASSED
tests/test_playbook.py::TestAcciones::test_crear_ticket_simulado PASSED
tests/test_playbook.py::TestAcciones::test_registrar_evidencia_crea_archivo PASSED
tests/test_playbook.py::TestAcciones::test_deshabilitar_cuenta_simulado PASSED
15 passed in 0.06s
```
运行并生成覆盖率报告：
```
pytest tests/ -v --cov=src --cov-report=term-missing
```
## 路线图
- [ ] 基于 FastAPI 的 REST Endpoint，用于接收来自外部 SIEM 的警报
- [ ] 实时监控警报目录的 Daemon 模式
- [ ] 通过 Slack 和 Microsoft Teams 的通知渠道
- [ ] 与 TheHive 集成进行案例管理
- [ ] 使用 Threat Intelligence 源（AbuseIPDB、OTX）丰富警报
- [ ] 在 AWS Lambda 进行 Serverless 部署
- [ ] 基于 Grafana 的指标仪表板
## 相关项目
该项目可与以下系统自然集成：
- **Log Analyzer** — 生成供此系统使用和执行的警报
- **IAM Audit Tool** — 可根据审计发现触发 `deshabilitar_cuenta` 操作
- **Threat Intel Feed Aggregator** — 在执行 playbook 之前使用 IoC 上下文丰富警报
## 许可证
MIT — 可自由使用、修改和分发。
*作为 Blue Team / SOC 作品集的一部分开发。与 MITRE ATT&CK 框架对齐。*
标签：CISA项目, Cloudflare, ESC漏洞, IP 地址批量处理, IR, MITRE ATT&CK, PB级数据处理, Playbook, Python, SOAR, YAML, 告警分诊, 告警映射, 安全事件自动化响应, 安全剧本, 安全告警, 安全库, 安全规则引擎, 安全运维, 工单系统, 数字取证, 无后门, 模拟运行, 电子取证, 私有化部署, 网络安全, 网络研究, 自动化安全防御, 自动化脚本, 自动封禁IP, 证据收集, 逆向工具, 防御规避, 隐私保护