Tamkeen-graduation-project/SOC-Automation-AI

# SOC-Automation-AI 🛡️ 一个基于 AI 的 **SOAR** (安全编排、自动化与响应) pipeline，集成了 **Wazuh SIEM**，可自动获取安全告警，使用威胁情报对其进行丰富，按风险等级进行分类，发送 HTML 电子邮件报告，并在获得人工批准后执行主动响应（IP 封禁）。 ## 📌 项目状态 | 组件 | 状态 | |-----------|--------| | 从 Wazuh Indexer 获取告警 | ✅ 已实现 | | OSINT 丰富 (AbuseIPDB + IPinfo) | ✅ 已实现 | | AI/风险分析器（基于规则的引擎） | ✅ 已实现 | | 电子邮件通知（通过 Gmail SMTP 发送 HTML） | ✅ 已实现 | | 主动响应 — Wazuh `firewall-drop` | ✅ 已实现 | | 主动响应 — Tamkeen 后端 API | ✅ 已实现 | | Pipeline 编排器 (`soar_pipeline.py`) | ✅ 已实现 | | Docker 镜像 + Docker Compose | ✅ 已实现 | | CI/CD (GitHub Actions) | ✅ 已实现 | | 集成真实的 LLM / ML 模型 | ⏳ 计划中（目前为基于规则的模拟） | ## 🏗️ 架构与 Pipeline ``` Wazuh Indexer (OpenSearch :9200) │ ▼ Stage 1 — FETCH wazuh_fetcher.py ──► alerts.json │ ▼ Stage 2 — ENRICH (optional, requires API keys) osint_enricher.py ──► alerts.json (adds osint{} block per alert) │ ▼ Stage 3 — ANALYZE ai_analyzer.py ──► analyzed_alerts.json │ ├── Stage 4 — NOTIFY (skippable) │ email_notifier.py ──► HTML report via Gmail SMTP │ └── Stage 5 — RESPOND (skippable, manual approval) active_response.py ──► Wazuh firewall-drop OR Tamkeen Backend /blockUser ``` 所有五个阶段均由 **`soar_pipeline.py`** 编排，它会按顺序运行这些阶段，并在每次运行后保存一个 `pipeline_log.json`。 ### 阶段详情 | 阶段 | 脚本 | 输出文件 | 可跳过 | |-------|--------|-------------|-----------| | 1 – 获取 | `wazuh_fetcher.py` | `alerts.json` | ❌ 必需 | | 2 – OSINT 丰富 | `osint_enricher.py` | `alerts.json` (已更新) | ✅ `--skip-osint` | | 3 – 分析 | `ai_analyzer.py` | `analyzed_alerts.json` | ❌ 必需 | | 4 – 通知 | `email_notifier.py` | (已发送邮件) | ✅ `--skip-email` | | 5 – 响应 | `active_response.py` | `response_log.json` | ✅ `--skip-response` | ## ✨ 功能特性 ### 已实现 - **Wazuh 告警获取器** — 通过 Wazuh Manager API (JWT) 进行身份验证，连接到 Wazuh Indexer (OpenSearch) 并查询 `wazuh-alerts-*` 索引。支持可配置的时间窗口 (`--minutes`) 和最低严重级别 (`--level`)。通过 `search_after` 自动分页。无论级别如何，Suricata IDS 告警始终包含在内。 - **OSINT 丰富器** — 对于告警中每个唯一的公共源 IP，查询 AbuseIPDB（滥用分数、报告数量、Tor 标记）和 IPinfo（地理位置、VPN/proxy/hosting 标记）。结果会合并回每个告警的 `osint{}` 块中。私有/RFC-1918 IP 将被跳过。每次运行的结果会被缓存以避免重复请求。 - **风险分析器** — 基于规则的引擎，为每个告警分配风险等级和建议的操作： - 🔴 **严重** (`block_ip`) — `rule_level ≥ 10` 或 Suricata 组，或者在 AbuseIPDB `abuseConfidenceScore` (0–100) ≥ 75 时，由 OSINT 驱动升级的中等风险告警。 - 🟡 **中等** (`investigate`) — `rule_level` 7–9。 - 🟢 **低** (`ignore`) — 其他所有情况。 - 添加 `ai_analysis{}` 块，包含 `risk`、`action`、`confidence`、`explanation`、`indicators` 和 `recommended_ttl_minutes`。 - **邮件通知器** — 构建一封深色主题的 HTML 电子邮件，包含执行摘要（严重/高/中/低风险计数）、建议封禁的 IP、最常触发的规则以及每个告警的详细信息。将完整的 `analyzed_alerts.json` 作为附件发送。通过 Gmail SMTP 使用 STARTTLS 发送。支持 `--dry-run` 以将本地 `email_preview.html` 保存到本地而不实际发送。 - **主动响应** — 读取 `analyzed_alerts.json`，提取 `action == "block_ip"` 的 IP，然后向操作员呈现每个 IP 以供人工批准 (`y / n / block-all / skip-all`)。两种封禁模式： - **Wazuh 模式** — 在指定 agent 上调用带 `!firewall-drop` 命令的 `PUT /active-response`。 - **后端模式** — 使用 `x-security-key` header（API key M2M 认证，无需 Wazuh）在 Tamkeen 后端调用 `POST /api/v1/users/blockUser`。 - **Docker** — 单个 `Dockerfile`，可在无限循环中（每 5 分钟）运行 `soar_pipeline.py`。`docker-compose.yaml` 从 Docker Hub 拉取预构建的镜像，并挂载 `./logs` 卷。 - **CI/CD** — 三个 GitHub Actions 工作流：CI（语法检查、Bandit SAST、pip-audit）、CD（在版本 tag 上构建并推送 Docker 镜像）、部署（在 `release-*` tag 上通过 SSH 部署到安全服务器）。 ### 计划中 / 尚未实现 - **真实的 LLM/ML 模型** — 将基于规则的 `analyze_alert()` 替换为调用 LLM（OpenAI、Gemini、Ollama）或训练好的 ML 分类器。只需更改 `analyze_alert()` 函数即可。 - **Slack / Teams 通知** — 在 `email_notifier.py` 之外增加额外的通知模块。 - **Web 仪表板** — 用于可视化 `pipeline_log.json` 和告警历史记录的 UI。 - **多 agent 主动响应** — 支持在单次运行中在多个 Wazuh agent 上进行封禁。 - **定时 / cron 执行** — 可配置的自动调度（目前由 Docker 容器通过每 5 分钟休眠的循环来处理）。 ## 📋 前置条件 | 需求 | 备注 | |-------------|-------| | Python 3.10+ | 也已通过 3.11 测试 | | Wazuh 4.x 技术栈 | Manager（端口 55000）+ Indexer/OpenSearch（端口 9200）。有关基于 Docker 的设置，请参阅 `wazuh-docker/`。 | | 带有应用密码的 Gmail 账户 | 用于电子邮件通知（必须启用两步验证） | | AbuseIPDB API key | 免费层级：每天 1,000 次请求 — [注册](https://www.abuseipdb.com/account/api) | | IPinfo token | 免费层级：每月 50,000 次请求 — [注册](https://ipinfo.io/signup) | | Docker + Docker Compose | 仅在容器化部署或运行 Wazuh 技术栈时需要 | | Tamkeen 后端 URL + API key | 仅在后端模式的 IP 封禁时需要 | ## ⚙️ 配置 将 `.env.example` 复制到 `.env` 并填入你的值。**切勿将 `.env` 提交到版本控制。** ``` cp .env.example .env ``` ``` # ── Wazuh Manager API ── WAZUH_HOST= # e.g. 127.0.0.1 or wazuh.manager WAZUH_MANAGER_PORT=55000 WAZUH_USER=wazuh-wui WAZUH_PASS= # ── Wazuh Indexer (OpenSearch) ── WAZUH_INDEXER_PORT=9200 WAZUH_INDEXER_USER=admin WAZUH_INDEXER_PASS= # ── 邮件 (Gmail SMTP) ── SMTP_FROM= SMTP_TO= SMTP_PASSWORD= # Google Account → Security → App Passwords # ── OSINT 威胁情报 (可选但推荐) ── ABUSEIPDB_API_KEY= IPINFO_TOKEN= # ── Tamkeen Backend 集成 (可选) ── BACKEND_URL=http://tamkeen_api:3000 # Use container name, not localhost, inside Docker SECURITY_API_KEY= ``` 所有变量也可以作为 CLI flag 传递；环境变量是备选方案。 ## 🚀 设置与运行 ### 本地（原生 Python） ``` # 1. Clone 并进入 repo git clone https://github.com/Tamkeen-graduation-project/SOC-Automation-AI.git cd SOC-Automation-AI # 2. 安装依赖 pip install -r requirements.txt # 3. 配置 cp .env.example .env # 使用你的 Wazuh 凭据、SMTP 设置和可选的 API keys 编辑 .env # 4. 运行完整 pipeline python soar_pipeline.py --host 127.0.0.1 --minutes 10 --level 6 # 或者跳过邮件和 active response，仅进行快速的 fetch+analyze python soar_pipeline.py --skip-email --skip-response # Dry run (不发送邮件，不封锁 IP) python soar_pipeline.py --dry-run ``` ### 运行单个模块 ``` # 阶段 1 — Fetch alerts (最近 10 分钟，level 6+) python wazuh_fetcher.py --minutes 10 --level 6 --output alerts.json # 阶段 1 — 仅 Health check python wazuh_fetcher.py --health # 阶段 2 — OSINT enrichment python osint_enricher.py --input alerts.json --output alerts.json --summary # 阶段 3 — Analyze python ai_analyzer.py --input alerts.json --output analyzed_alerts.json --summary # 阶段 4 — 邮件报告 (dry run 会将 email_preview.html 保存在本地) python email_notifier.py --input analyzed_alerts.json --dry-run # 阶段 4 — 发送真实邮件 python email_notifier.py --input analyzed_alerts.json # 阶段 5 — Active response (交互式，dry run) python active_response.py --input analyzed_alerts.json --dry-run # 阶段 5 — 通过 Tamkeen Backend API 进行 Active response python active_response.py --input analyzed_alerts.json \ --backend-url http://localhost:3000 --backend-api-key ``` ### Docker ``` # 1. 配置 (Docker 会自动读取 .env) cp .env.example .env # 编辑 .env # 2. 运行 pipeline container (从 Docker Hub 拉取预构建镜像) docker compose up -d # 查看日志 docker logs -f soc_soar_pipeline ``` 容器会在连续循环中运行 `soar_pipeline.py`，每次运行之间休眠 5 分钟。 要在本地构建镜像而不是拉取： ``` docker build -t soc-automation-ai:local . docker run --env-file .env soc-automation-ai:local ``` ### 在本地运行 Wazuh 技术栈 `wazuh-docker/single-node/` 中包含了一个基于 Docker 的单节点 Wazuh 4.x 设置（Manager + Indexer + Dashboard）： ``` cd wazuh-docker/single-node docker compose up -d ``` | 服务 | 端口 | 用途 | |---------|------|---------| | Wazuh Manager | 55000 | API — 身份验证，主动响应 | | Wazuh Indexer (OpenSearch) | 9200 | 告警存储和搜索 | | Wazuh Dashboard | 443 | 用于监控的 Web UI | ## 🔗 Wazuh 集成 ### 连接方式 1. **身份验证** — `wazuh_fetcher.py` 和 `active_response.py` 使用 basic auth 在 Manager API 上调用 `POST /security/user/authenticate`，并接收一个 JWT token。 2. **告警查询** — 获取器向 `https://:9200/wazuh-alerts-*/_search` 发送 OpenSearch 查询，带有时间范围过滤器和严重性过滤器（规则级别和/或 Suricata 组）。通过 `search_after` 自动处理分页。 3. **主动响应** — `active_response.py` 调用带 `!firewall-drop` 命令的 `PUT /active-response?agents_list=`，这会在目标 agent 上添加一条 `iptables` 规则。 ### SSL 说明 Pipeline 在调用 Wazuh API 时使用 `verify=False`，因为默认的 Wazuh Docker 设置使用自签名证书。`urllib3` 的 InsecureRequestWarning 被抑制。在具有有效证书的生产环境部署中，请移除 `verify=False` flag 和 `urllib3.disable_warnings()` 调用。 ### 通过 dry run 进行测试 `--dry-run` flag 可在 `soar_pipeline.py` 和单个模块上使用： - **电子邮件：** 将 HTML 保存到 `email_preview.html` 而不是发送。 - **主动响应：** 打印将被封禁的内容，而不调用任何 API。 ``` # 无副作用的端到端测试 python soar_pipeline.py --dry-run --skip-osint ``` ## 📁 仓库结构 ``` SOC-Automation-AI/ │ ├── soar_pipeline.py # Main orchestrator — runs all 5 stages in sequence ├── wazuh_fetcher.py # Stage 1 — Fetch alerts from Wazuh Indexer (OpenSearch) ├── osint_enricher.py # Stage 2 — Enrich IPs via AbuseIPDB + IPinfo ├── ai_analyzer.py # Stage 3 — Rule-based risk classifier (mock AI engine) ├── email_notifier.py # Stage 4 — Send HTML security report via Gmail SMTP ├── active_response.py # Stage 5 — Block IPs via Wazuh API or Tamkeen Backend │ ├── Dockerfile # Builds the SOC pipeline image (runs every 5 min) ├── docker-compose.yaml # Pulls pre-built image from Docker Hub, mounts ./logs │ ├── wazuh-docker/ # Wazuh 4.x Docker configurations │ ├── single-node/ # Single-node setup (Manager + Indexer + Dashboard) │ └── multi-node/ # Multi-node setup │ ├── .env.example # Configuration template — copy to .env and fill in secrets ├── requirements.txt # Python dependencies (requests, python-dotenv, urllib3) ├── .gitignore # Excludes .env, pipeline output JSON files, caches │ ├── .github/ │ └── workflows/ │ ├── ci.yml # CI: syntax check, Bandit SAST, pip-audit │ ├── CD.yml # CD: Docker build & push on version tags (v*) │ └── deploy.yml # Deploy: SSH deploy to security server on release-* tags │ ├── AI_SEC_Features_Overview.md # Arabic-language project overview └── walkthrough.md # Arabic-language detailed module walkthrough ``` **Pipeline 输出文件**（自动生成，未提交）： | 文件 | 创建者 | 内容 | |------|-----------|----------| | `alerts.json` | 阶段 1（+ 阶段 2 会更新它） | 原始 + OSINT 丰富的告警 | | `analyzed_alerts.json` | 阶段 3 | 带有 `ai_analysis{}` 块的告警 | | `response_log.json` | 阶段 5 | IP 封禁决策的审计追踪 | | `pipeline_log.json` | 编排器 | 各阶段的耗时和状态 | | `email_preview.html` | 阶段 4（仅在 dry run 时） | 用于本地检查的电子邮件正文 | ## 🔧 故障排除 ### `无法连接到 https://... 的 Wazuh Manager` - 确认 Wazuh 容器正在运行：`docker ps` - 检查 `.env` 中的 `WAZUH_HOST` 和 `WAZUH_MANAGER_PORT`。 - 验证防火墙/网络规则是否允许端口 55000 上的流量。 ### `认证失败 — 用户名或密码错误` - 默认的 Wazuh API 凭据为 `wazuh-wui` / Wazuh Dashboard 首次登录界面中显示的密码。 - `.env` 中的 `WAZUH_PASS` 必须与 **API 用户** 密码匹配，而不是 dashboard 管理员密码。 ### `Indexer 认证失败` - `WAZUH_INDEXER_USER` 默认为 `admin`；密码必须与 Wazuh 安装期间设置的密码匹配（检查 `wazuh-docker/single-node/config/wazuh_indexer/internal_users.yml`）。 ### 未返回任何告警 - 扩大时间窗口：`--minutes 60`。 - 降低严重性阈值：`--level 3`。 - 确认至少有一个 Wazuh agent 已注册并正在生成事件。 ### Gmail `SMTPAuthenticationError` - 创建一个 **Gmail 应用密码**（Google 账户 → 安全性 → 两步验证 → 应用密码），并将其用作 `SMTP_PASSWORD`，而不是你常规的 Gmail 密码。 ### OSINT 丰富被跳过 - 只有在设置了 `ABUSEIPDB_API_KEY` 的情况下才会运行 OSINT。如果缺少该 key，阶段 2 将自动跳过且不会报错。 ### `找不到文件：analyzed_alerts.json` - 在运行阶段 4 或阶段 5 之前，务必先运行阶段 3 (`ai_analyzer.py`)。 - 使用 `soar_pipeline.py` 时，各阶段会自动按顺序运行。 ### Docker 容器立即退出 - 检查日志：`docker logs soc_soar_pipeline` - 最可能的原因是缺少 `.env` 文件或未设置 `WAZUH_PASS` / `WAZUH_INDEXER_PASS`。 ## ⚙️ CI/CD 与安全检查 GitHub Actions 工作流会在每次推送到 `main` / `testing` 分支以及拉取请求时运行： - **语法检查** — `python -m compileall .` - **SAST (Bandit)** —针对安全问题进行 Python 静态分析（中 + 高严重性） - **依赖审计 (pip-audit)** — 扫描 `requirements.txt` 以查找已知的 CVE 在 `v*` tag 上：将构建 Docker 镜像并推送到 Docker Hub 上的 `tamkeengraduationproject/soc-automation-ai:`。 在 `release-*` tag 上：通过 SSH 将 `docker-compose.yaml` 部署到安全服务器。 *作为 Tamkeen 毕业项目的一部分开发。*

标签：Python, SOAR, Wazuh, 威胁情报, 安全运营, 开发者工具, 扫描框架, 无后门, 请求拦截, 逆向工具