builtbyraman/babel_elastic

# Babel 网络安全简直就是一个现实版的 Babel —— 每个平台都说着不同的“方言”，而为某个平台编写的检测规则几乎无法在另一个平台上运行。Babel 扭转了这一挑战：它构建于更新的 [SIGMA](https://sigmahq.io/) 开放标准之上，并在现代化的 Elastic 和 Kibana 中原生运行，使安全团队能够通过一个与事件响应生命周期以及战术、技术和程序相契合的单一界面，跨平台和工具编写、转换、测试、部署和跟踪检测规则。 ## 截图 ### 规则编辑器 在 YAML 编辑器（左侧）中编写 SIGMA 规则，在可视化编辑器（中间）查看自动填充的字段，并在 Elasticsearch 输出面板（右侧）获得即时格式转换。输出上方有一键式 **在 Discover 中打开**、**回测** 和 **部署** 操作。  ### 真实规则 — 完整元数据与 EQL 转换 从规则库加载任何规则，以查看其完整的 SIGMA YAML、自动填充的可视化编辑器字段（标题、状态、级别、描述、logsource、MITRE 标签、IR 阶段）以及实时转换的输出。在这里，一个 AWS CloudTrail 规则只需点击一下即可转换为 EQL。  ### 多格式转换 从下拉菜单中切换输出格式 —— Lucene、EQL、ES|QL、Query DSL、Kibana NDJSON、SIEM Rule 或 ElastAlert —— 转换后的查询将即时更新。  ### MITRE ATT&CK 覆盖热力图 覆盖视图将您的规则库映射到所有 14 个 ATT&CK 战略。每个单元格使用六级色标显示技术覆盖情况：无覆盖 → 1 条规则 → 2–5 → 6–10 → 11–20 → 20+ 条规则。汇总统计数据展示了总规则数、命中的技术数以及覆盖的战略数。  ### IR 就绪度报告 IR 就绪度选项卡根据五种威胁场景（勒索软件、APT、内部威胁、数据泄露和供应链）评估检测覆盖率。选择一个场景并点击分析，即可获得逐阶段的分解情况。  运行内部威胁场景显示在 5/5 个阶段中实现了 94% 的技术覆盖，并列出了每个阶段已覆盖和缺失的技术，以及提供覆盖的具体规则。  ### 数据源感知 数据源选项卡将您的 Elasticsearch 索引映射到 SIGMA logsource 类别。没有匹配索引数据的源会被标记 —— 在数据被接入之前，针对这些源的规则不会产生警报。  ### 规则库 “选择规则”浮层支持按标题、描述或技术 ID 搜索所有 3,730 条已同步规则。按战略或 IR 阶段进行过滤；点击任意行即可将该规则直接加载到编辑器中。  ### GitHub 仓库设置 将多个 GitHub 仓库配置为规则源 —— 包括同一仓库内的独立路径。规则按仓库进行同步，且保持完全隔离。  ### 集成状态 设置面板显示 Babel API 和 Elasticsearch 的实时连接状态、可用的数据源类别以及所有已配置仓库及其启用状态。  ## 功能 - **YAML 编辑器** —— 编写和验证 SIGMA 规则，并提供实时语法反馈 - **可视化规则构建器** —— 无需编写原始 YAML 即可构建规则 - **多 SIEM 转换** —— 将规则转换为 8 种输出格式： - Lucene query string - Query DSL - Kibana NDJSON - SIEM Rule (JSON / NDJSON) - EQL - ES|QL - ElastAlert - **实时规则测试** —— 针对带有命中聚类的 Elasticsearch 索引进行回测 - **规则部署** —— 将规则直接推送到 Kibana Detection Engine - **MITRE ATT&CK 覆盖热力图** —— 将您规则集的技术覆盖情况可视化 - **IR 就绪度评估** —— 将规则映射到事件响应阶段 - **字段建议** —— 自动将 SIGMA 字段映射到 ECS 字段 - **Schema 偏移检测** —— 随时间跟踪 Elasticsearch mapping 的变化 - **规则质量评分** —— 评估规则的有效性和陈旧度 - **数据源可用性映射** —— 检查可用的索引、文档计数和字段 mapping - **GitHub 同步** —— 从多个可配置的 GitHub 仓库（SigmaHQ 和自定义仓库）拉取规则；所有规则均可同步，数量无上限 ## 要求 ### 运行时 | 依赖 | 版本 | 说明 | |---|---|---| | Kibana / Elasticsearch | 9.3.4 | 已固定 —— 请参阅下方说明 | | Python | 3.11+ | Babel API 必需 | ### 构建工具 | 依赖 | 版本 | 说明 | |---|---|---| | Node.js | 20+ | 仅构建时需要 | | `zip` CLI | 任意 | 仅构建时需要 | ### npm 包（运行时） | 包名 | 版本 | |---|---| | `@elastic/eui` | ^114.3.0 | | `js-yaml` | ^4.2.0 | | `react` | ^18.3.1 | | `react-dom` | ^18.3.1 | ### npm 包（开发 / 构建） | 包名 | 版本 | |---|---| | `typescript` | ^5.9.3 | | `webpack` | ^5.107.2 | | `webpack-cli` | ^6.0.1 | | `ts-loader` | ^9.6.0 | | `html-webpack-plugin` | ^5.6.7 | | `jest` | ^30.4.2 | | `jest-environment-jsdom` | ^30.4.1 | | `ts-jest` | ^29.4.11 | | `@testing-library/react` | ^16.3.2 | | `@types/node` | ^20.19.42 | | `@types/react` | ^18.3.31 | | `@types/react-dom` | ^18.3.7 | | `@types/jest` | ^30.0.0 | | `@types/js-yaml` | ^4.0.9 | ### Python 包（Sigma 转换引擎） 这些是 `server/translation_script/sigma/` 所需的。在构建或运行转换脚本之前，请先设置虚拟环境： | 包名 | 版本 | |---|---| | `pySigma` | >=0.11.0, <1.0.0 | | `pySigma-backend-elasticsearch` | >=1.0.0, <2.0.0 | ## 快速开始（Docker Compose） 完整技术栈 —— Elasticsearch、Kibana（包含 Babel）和 Babel API —— 只需一条命令即可启动。 ### 1. 配置凭证 ``` cp .env.example .env ``` 编辑 `.env` 并至少设置以下内容： | 变量 | 用途 | |---|---| | `ELASTIC_PASSWORD` | `elastic` 超级用户的密码 | | `KIBANA_SYSTEM_PASSWORD` | 内部 Kibana 服务账号密码 | | `KIBANA_ENCRYPTION_KEY` | 用于加密保存对象的 32 字符密钥 | ### 2. 构建 Kibana 插件（一次性） ``` npm install KIBANA_VERSION=9.3.4 npm run build ``` 仅在修改插件源代码时才需重复此步骤。正常重启（`docker-compose up -d`）不需要重新构建。 ### 3. 启动技术栈 ``` docker-compose up --build -d ``` 这将按依赖顺序启动四个服务： | 服务 | 容器 | 端口 | 用途 | |---|---|---|---| | Elasticsearch | `babel-es` | 9200 | 规则存储和实时规则测试 | | kibana-setup | *(初始化后退出)* | — | 仅设置一次 `kibana_system` 账号密码 | | Babel API | `babel-api` | 8001 | 规则转换、验证、覆盖率、IR 就绪度 | | Kibana + Babel | `babel-kibana` | 5601 | UI | 首次启动时会拉取镜像并安装 Python 依赖（约 2–3 分钟）。随后的启动速度会很快。 ### 4. 验证技术栈是否已启动 ``` # Babel API curl http://localhost:8001/health # → {"status": "ok", "service": "sigma-api"} # Kibana curl -u elastic: http://localhost:5601/api/babel/status # → services: [{name: "Sigma Conversion API", status: "ok"}, {name: "Elasticsearch", status: "ok"}] ``` Kibana 可通过 **http://localhost:5601** 访问 —— 使用 `.env` 中的密码以 `elastic` 身份登录。 在左侧导航栏中转到 **Babel**。要检查服务连通性，请点击 Babel 导航栏中的 **齿轮图标 (⚙)** 以打开设置 —— 面板底部会显示 Babel API 和 Elasticsearch 的实时状态。 ### 5.（仅在首次启动时）从 GitHub 同步规则 规则库（`babel_sigma_doc` 索引）在首次启动时为空。在 Babel UI 中： 1. 转到 **设置** → 添加一个 GitHub 仓库（例如 `https://github.com/SigmaHQ/sigma`，分支 `master`，路径 `rules/`） 2. 点击 **同步** —— 这将从仓库获取所有 SIGMA YAML 文件 3. 返回 **规则库** 选项卡；规则将随着同步完成而出现 ### 停止和重启 ``` docker-compose down # stop (data volumes preserved) docker-compose down -v # stop and wipe all data (fresh start) docker-compose up -d # restart without rebuilding images docker-compose up --build -d # rebuild images (after source changes) ``` ## 架构：Babel API Babel 的转换、验证和分析功能由内置的 **Babel API** 处理 —— 这是一个基于 [pySigma](https://github.com/SigmaHQ/pySigma) 和 Elasticsearch 后端构建的 Python Flask 服务。它作为独立的容器（`babel-api`）运行，因此 Kibana 插件可保持纯 JavaScript，而没有 Python 运行时依赖。 ``` Kibana (Babel plugin) │ proxy requests ▼ Babel API (babel-api:8001) Elasticsearch (babel-es:9200) ├─ POST /v1/conversions ├─ babel_sigma_doc (rule library) ├─ POST /v1/rules/validate └─ babel_config (settings) ├─ POST /v1/coverage ├─ POST /v1/coverage/navigator-export ├─ POST /v1/ir-readiness ├─ GET /v1/fields[?category=…] ├─ POST /v1/fields/suggest ├─ POST /v1/rules/quality └─ POST /v1/test-runs ← also queries Elasticsearch ``` Babel API 的源代码位于 `sigma-api/` 中，由 `docker-compose up --build` 自动构建。 ### API 的作用 - 将 SIGMA YAML 转换为 Lucene、EQL、ES|QL、Kibana NDJSON、SIEM Rule 和 ElastAlert - 通过 pySigma 验证规则语法和结构 - 为 logsource/detection 字段建议 ECS 字段映射 - 对规则质量（标题、描述、参考、标签、级别、状态）进行评分 - 将规则映射到 MITRE ATT&CK 技术，以生成覆盖热力图 - 评估勒索软件、APT、内部威胁、数据泄露和供应链场景下的 IR 就绪度 - 针对 Elasticsearch 索引运行实时规则测试 ### 没有 API 时会降级的功能 如果无法访问 Babel API，调用该 API 的功能将返回错误。没有 API 也能正常工作的功能包括： | 功能 | 需要 API | |---|---| | 规则编辑器（YAML 编辑、保存） | 否 | | 规则库（浏览、搜索、从 GitHub 同步） | 否 | | 规则转换 / 翻译 | **是** | | 规则验证 | **是** | | 将规则部署到 Detection Engine | **是**（转换步骤） | | MITRE ATT&CK 覆盖热力图 | **是** | | IR 就绪度评估 | **是** | | 字段映射建议 | **是** | | 规则质量评分 | **是** | | 实时规则测试（回测） | **是** | ### API 认证 在 `.env` 中设置 `SIGMA_API_KEY` 将要求所有 Babel API 请求都包含 bearer token。将其留空（默认值）则允许在 Docker 网络内进行未经身份验证的访问。 ## 安装 Babel 是一个 **Kibana 插件**。它不是 Elastic 集成，无法从 Kibana 集成页面（Fleet → Integrations）安装。该页面用于 Elastic Agent集成，它们使用完全不同的格式。尝试在那里安装 Babel 将失败并报 `manifest.yml not found` 错误。 有两种受支持的安装方法： ### 选项 A —— Docker Compose（推荐） 这是让完整技术栈运行起来的最快方法。Elasticsearch、Kibana 和 Babel API 将同时启动： ``` cp .env.example .env # configure credentials npm install && KIBANA_VERSION=9.3.4 npm run build # one-time plugin build docker-compose up --build -d # start the stack ``` 有关完整流程，请参阅 [快速开始（Docker Compose）](#quick-start-docker-compose)。 ### 选项 B —— 手动安装到现有的 Kibana 中 如果您已经运行了 Kibana 并想向其添加 Babel： ``` # 安装期间必须停止 Kibana bin/kibana-plugin install file:///absolute/path/to/babel-9.3.4.zip ``` 然后配置 `kibana.yml`（参见[配置](#configuration)）并重启 Kibana。 要卸载： ``` bin/kibana-plugin remove babel ``` ## 从源代码构建 ### 1. 安装 Node 依赖 ``` npm install ``` ### 2. 构建 构建脚本会从本地安装或名为 `kibana-local-dev` 的运行中的 Docker 容器自动检测您的 Kibana 版本。如果两者都不存在，请显式设置版本： ``` KIBANA_VERSION=9.3.4 npm run build ``` 成功后，该脚本将生成： - `target/babel/` —— 组装好的插件目录 - `target/babel-.zip` —— 可用于 `kibana-plugin install` 的可分发 zip 文件 如果 Docker 容器 `kibana-local-dev` 正在运行，该脚本还会将插件复制到容器中并自动重启 Kibana。 ### 4. 手动安装（无 Docker） ``` cp -r target/babel/ /usr/share/kibana/plugins/babel # 然后重启 Kibana ``` ## 配置 将以下内容添加到 `kibana.yml`： ``` # Babel API 的 URL — 必填项，在 Docker 外部无默认值可用 babel.sigmaApiUrl: "http://:/v1" # 部署检测规则时 Kibana 用于调用自身的 URL # 本地测试默认为 http://localhost:5601 — 如果 Kibana 位于 proxy 之后或在不同主机上，请进行修改。示例如下： babel.kibanaUrl: "http://localhost:5601" ``` ### 环境变量（可选） | 变量 | 用途 | |---|---| | `SIGMA_API_KEY` | 如果 Babel API 需要身份验证，转发给 Babel API 的 bearer token | ## Elasticsearch 前置条件 该插件会在您的 Elasticsearch 集群中创建并使用两个索引： | 索引 | 用途 | |---|---| | `babel_sigma_doc` | 从 GitHub 仓库同步的规则库 | | `babel_config` | 插件设置（GitHub token，已配置的仓库） | **当 Kibana 以具有索引创建权限的用户连接时**，这两个索引都会在首次运行时自动引导创建。有两种情况需要手动创建： - 集群上设置了 `action.auto_create_index: false` - Kibana 被配置为使用内置的 `kibana_system` 用户（常见于 `elastic-start-local`），该用户没有 `indices:admin/create` 权限 在这两种情况下，请在启动 Kibana 之前使用 `elastic` 超级用户创建索引： ``` curl -X PUT "http://localhost:9200/babel_config" curl -X PUT "http://localhost:9200/babel_sigma_doc" ``` ### GitHub 速率限制 规则同步功能会从 GitHub 逐个获取 YAML 文件。如果没有 token，GitHub 仅允许每小时 60 次未经身份验证的请求 —— 这不足以同步像 SigmaHQ 这样的大型仓库（约 3,000 条规则）。**强烈建议使用 GitHub Personal Access Token。** 请使用仅在目标仓库上具有 `Contents: Read` 权限的细粒度 PAT。将其存储在插件的设置 → GitHub Token 中。 ### 授权 所有插件 API 路由均可由任何经过身份验证的 Kibana 用户访问。没有基于路由的 RBAC —— 只读分析师可以像管理员一样部署规则。如果需要，请在 Kibana Space 或网络层面限制访问。 ## 开发 ``` # 类型检查而不构建 npm run typecheck # 运行测试（涵盖 server + public 的 79 个测试） npm test # 完整构建 KIBANA_VERSION=9.3.4 npm run build ``` ### 项目结构 ``` public/ components/ React UI components hooks/ Custom hooks (editor sync, auto pipeline selection) services/ API client context/ Kibana service provider server/ routes/ Kibana server-side API routes translation_script/sigma/ Python SIGMA conversion engine (pySigma) plugin.ts Kibana plugin lifecycle config.ts Plugin configuration schema scripts/ build.js Build orchestrator (typecheck → compile → webpack → zip) .github/ workflows/ci.yml CI: typecheck, test, build, upload zip artifact ``` ## 许可证 根据 [Apache License 2.0](LICENSE) 获得许可。可免费使用、修改和分发 —— 包括在商业和企业环境中 —— 且没有开源您修改内容的义务。

标签：Elasticsearch, Kibana插件, SIGMA规则, 响应拦截, 安全运营, 扫描框架, 请求拦截, 越狱测试, 逆向工具