majiinB/Wazuh-AI-Integration

# Wazuh AI 集成 一个现代的 AI 辅助安全警报关联和分析平台，与 [Wazuh](https://wazuh.com/) 集成。此存储库包含运行和开发 webhook 驱动的、异步警报处理堆栈的代码、容器和脚本，该堆栈结合了确定性关联、IOC 丰富、运行手册的语义检索和可选的 LLM 辅助摘要。 ## 概述 Wazuh AI 集成旨在以规模处理 Wazuh 警报，同时最大限度地减少误报并向 SRE 提供可操作上下文。与较旧文档相比，以下是一些重要说明： - 摄入是 webhook 驱动的：Wazuh Manager（或轻量级转发器/集成器）将警报有效负载 POST 到 Django webhook 端点。系统不依赖于 ES API 轮询进行实时摄入。 - 知识库（KB/运行手册）用于检索以向 SRE 提供参考。KB 内容不会盲目注入到 LLM 提示中——检索点将操作员指向运行手册和片段，而不是将整个 KB 提供给模型。 - MITRE ATT&CK 已集成到关联、去重、攻击会话组装和前向过滤中；之前路线图中的添加 MITRE 映射项被认为是完整的。 关键功能： - webhook 驱动的摄入，具有快速确认和内联处理 - 处理使用关联回退重试来容忍索引器延迟；长时间运行的 ops（RAG 查询、LLM 调用）目前在内联请求生命周期中运行 - 双重门过滤：前向过滤 + 噪音过滤 - IOC 关联引擎（指标匹配和丰富） - 在 `logs/utils/log_util.py` 中进行三层 IOC/上下文提取（`extract_iocs`）： - 第一层：直接 Wazuh 规则/代理有效负载字段 - 第二层：MITRE、IP、用户、端口和其他丰富警报字段 - 第三层：解码器特定的命令/进程/上下文字段 - 在任何 LLM/第三方调用之前执行掩码/编辑层 - 可选的 LLM（Google Gemini）用于摘要，具有确定性回退 - 对 SRE Watchtower/外部系统进行签名的 webhook 外发 ## 架构（高级） 流程摘要： -- Wazuh Manager -> Integrator/forwarder -> Django `/webhook/` 摄入端点 -- 摄入处理程序内联处理有效负载；处理管道运行以下按顺序步骤： 1. 前向过滤（摄入门） 2. 三层 IOC/上下文提取 3. IOC 关联引擎 4. 去重 & 攻击会话组装 5. 噪音过滤（上下文抑制） 6. 掩码/编辑（删除 PII/敏感字段） 7. 可选的 LLM 调用（Gemini）。如果 LLM 不可用，则使用模板化摘要和确定性启发式算法 处理后的事件持久化到 PostgreSQL 并在 `pgvector` 中索引以进行语义搜索。结果显示在 Next.js Watchtower 仪表板中，并通过签名的回调 webhook 发送到配置的 SRE 端点。 ## 组件 - `services/wazuh-ai/` — Django 后端，公开摄入端点、控制 API、处理管道、IOC 引擎、掩码和外发 webhook 逻辑 - `client/wazuh-test-client/` — SRE 使用的 Next.js Watchtower 仪表板 - `services/wazuh-postgre-database/` — PostgreSQL 容器和 init SQL - `wazuh-docker/` — 用于测试的参考 Wazuh 单节点和多节点部署 - `scripts/container-util/` — 有用的开发包装器：启动/停止/重建/状态/开发外壳，用于本地开发 - `scripts/simulations/` — canned 攻击场景和小脚本，用于生成测试关联和 IOC 逻辑的警报流量 - 重要系统行为（详细信息） - 摄入处理：webhook 处理程序验证有效负载并在内联运行管道。代码实现了关联回退重试（请参阅 `logs/services/ingest_service.py`），以在执行关联查询时容忍索引器延迟。 - 双重门过滤： - 前向过滤：在排队重处理之前，在摄入时进行便宜检查，可以丢弃低价值事件 - 噪音过滤：在关联/组装之后使用的更细粒度的抑制，以减少 SRE 的噪音 - IOC 关联引擎：将警报与已知的 IOC/指标匹配，并使用指标元数据和来源丰富事件 - 掩码/编辑：在 LLM 或外部 POST 之前确定性地删除或编辑 PII 和其他敏感字段。可配置列表位于 `services/wazuh-ai/config/` 下。 - 三层提取作为从警报有效负载中提取 IOC/上下文实现： - 第一层：规则/代理元数据和原始有效负载字段 - 第二层：MITRE、IP、用户和端口丰富 - 第三层：解码器特定的上下文，例如命令/进程细节 - LLM 回退：如果 Gemini 不可用（错误/速率限制），则系统记录失败并使用模板化摘要和确定性启发式算法，以确保管道输出仍然可用。 ## 先决条件 - Docker 20.10+ 和 Docker Compose v2 - Bash（用于辅助脚本） - 推荐：运行完整堆栈的本地 8GB+ RAM - （可选）Google Gemini API 密钥用于 LLM 功能 注意：系统以 webhook 为先；您不需要 ES API 轮询进行生产摄入。 ## 快速入门 1. 通过交互式设置配置环境： ``` bash setup.sh ``` 2. 构建 和 启动 堆栈： ``` docker compose up -d --build ``` 3. 验证服务和日志： ``` docker compose ps docker compose logs -f wazuh-ai-app docker compose logs -f wazuh-test-client ``` 4. 打开仪表板：http://localhost:3000 ## 配置（重点） 关键 `.env` 变量（示例）： ``` WAZUH_NETWORK_NAME=single-node_default POSTGRES_DB=wazuh_django_db POSTGRES_USER=django_user POSTGRES_PASSWORD=your_secure_password POSTGRES_PORT=5432 AI_APP_PORT=8000 HIGH_SEVERITY_THRESHOLD=10 WATCHTOWER_CALLBACK_URL=https://watchtower.example/callback CALLBACK_SECRET=supersecret GEMINI_API_KEY=optional ``` 前向过滤/噪音过滤/提取规则存储在 `services/wazuh-ai/config/` 中作为 YAML 文件，以便于针对特定环境进行微调。 ## 脚本和开发者工具 - `scripts/container-util/`：用于常见开发任务的便利包装器（启动/停止/重建、状态、开发外壳）。它们包装 `docker compose` 并应用一致的 env 设置，以进行本地迭代。 - `scripts/simulations/`：场景脚本和链（例如，`full_attack_chain.sh`），用于生成针对本地代理或索引器的合成警报流，以测试关联和丰富逻辑。 ## 开发说明 - 前端：`client/wazuh-test-client/` — 使用 `pnpm` 或 `npm` 在本地运行 Next.js 应用（请参阅该文件夹中的包清单）。 -- 后端：`services/wazuh-ai/` — Django 项目。在开发中，首选容器化服务以反映生产行为。 常见开发命令： ``` docker compose up -d --build docker compose exec -it wazuh-ai-app bash cd client/wazuh-test-client && pnpm install && pnpm dev ``` ## 模拟 使用 `scripts/simulations/setup.sh` 和链/单个脚本生成测试数据。这些练习有助于验证 IOC 引擎、关联窗口和过滤规则。 ## 服务概述 - `wazuh-ai`（Django）：webhook 摄入、处理管道、IOC 引擎、掩码和外发钩子 - `wazuh-test-client`（Next.js）：Watchtower 仪表板 - `services/wazuh-postgre-database/`：Postgres + init SQL ## 故障排除 - 容器日志：`docker compose logs -f ` -- 注意：此存储库目前不包括 Celery 任务队列；处理在摄入路径中同步运行。如果您计划迁移到 Celery，请将 `celery` 添加到 `requirements.txt` 中，并引入生产者/工作者和一个代理（Redis/RabbitMQ）。 -- LLM 错误：检查 `wazuh-ai` 日志中的 `LLM fallback` 消息——回退逻辑确保事件仍然得到摘要 - 签名的 webhook 失败：验证 `CALLBACK_SECRET` 和容器到回调 URL 的网络可达性 ## 关注的文件 - `services/wazuh-ai/` — 处理管道和配置 - `services/wazuh-ai/config/` — 前向/噪音过滤 YAML 和提取配置 - `scripts/container-util/` — 开发者容器助手 - `scripts/simulations/` — 攻击模拟脚本 - `client/wazuh-test-client/` — 仪表板 UI ## 路线图 - [ ] 高级关联算法（基于 ML） - [x] MITRE ATT&CK 映射（集成到关联、去重和会话组装中） - [ ] SOAR 平台集成（Splunk Phantom、Demisto） - [ ] 多租户支持 - [ ] 高级 RBAC - [ ] 审计日志 - [ ] Kubernetes 部署模板 ## 致谢 使用以下工具构建： - [Wazuh](https://wazuh.com/) - [Django](https://www.djangoproject.com/) - [Next.js](https://nextjs.org/) - [PostgreSQL](https://www.postgresql.org/) + [pgvector](https://github.com/pgvector/pgvector) **最后更新时间：2026 年 5 月 31 日** **版本：1.1.0**

标签：测试用例, 自动化攻击, 请求拦截, 逆向工具