grafana/sigma-rule-deployment

# Sigma Rule Deployment GitHub Actions 套件 使用声明式配置文件，通过 [GitHub Actions](https://sigmahq.io/) 自动化 [Sigma 规则](https://sigmahq.io/) 到 [Grafana Alerting](https://grafana.com/docs/grafana/latest/alerting/) 规则的转换、测试和部署，采用 [Detection as Code](./README.md#what-is-detection-as-code) (代码化检测) 方法。 ## 可用的 Actions - [**Config Validator**](./actions/validate/README.md): 根据 JSON schema 验证配置文件，以确保在处理之前结构和必填字段正确无误。 - [**Sigma Rule Validation**](./actions/sigma-validation/README.md): 在转换和部署 Sigma 规则之前，我们强烈建议对其进行验证，以确保它们符合 [Sigma 规范](https://sigmahq.io/docs/)。使用 [SigmaHQ Sigma Rules Validator](https://github.com/SigmaHQ/sigma-rules-validator) GitHub Action 在您的 CI/CD 流水线中自动验证规则。 - [**Sigma Rule Converter**](./actions/convert/README.md): 使用 `sigma-cli` 将 Sigma 规则转换为目标查询语言。支持动态插件安装、自定义配置和输出管理，生成包含转换后的查询和规则元数据的 JSON 输出文件。 - [**Grafana Query Integrator**](./actions/integrate/README.md): 处理来自 Sigma Rule Converter 的 JSON 输出，并生成 Grafana 兼容的告警规则配置，在转换后的 Sigma 规则和 Grafana alerting 之间架起桥梁。 - [**Sigma Rule Deployer**](./actions/deploy/README.md): 将告警规则文件部署到 Grafana，支持增量部署（仅限更改的文件）和全新部署（完全替换）。 ## 用法 1. 创建一个 GitHub 仓库，并添加您想要转换的 [Sigma rules](https://sigmahq.io/docs/basics/rules.html) 和 [pipelines](https://sigmahq.io/docs/digging-deeper/pipelines.html) - 遵循主要的 [SigmaHQ/sigma](https://github.com/SigmaHQ/sigma) 约定，我们将规则放入以 `rules` 开头的文件夹中，并将 Sigma pipelines 放入 `pipelines` 文件夹中 - 请注意，您想要转换的任何 [Sigma correlation rules](https://sigmahq.io/docs/meta/correlations.html) 必须将其引用的规则放在同一个文件中（参见 [FAQ](#faq)） 2. 创建一个 [Grafana service account token](https://grafana.com/docs/grafana/latest/administration/service-accounts/) 并将其 [作为 secret 添加](https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions) 到您的 GitHub 仓库 - 确保服务账户是 Editor，或者具有以下 [RBAC roles](https://grafana.com/docs/grafana/latest/administration/service-accounts/#assign-roles-to-a-service-account-in-grafana)： - Alerting: Access to alert rules provisioning API - Alerting: Rules Reader - Alerting: Rules Writer - Alerting: Set provisioning status - Data sources: Reader 3. 创建一个定义了一个或多个转换的配置文件，并将其添加到仓库中 - 参见示例 [configuration file](config/config-example.yml) - 更多详情请参见 [configuration file schema](config/schema.json) 4. 添加一个工作流，以便在 PR commit 或 issue comment 上运行 conversion/integration Actions - 参见可复用工作流 [convert-integrate.yml](.github/workflows/convert-integrate.yml) 5. 添加一个工作流，以便在推送到 main 分支时运行 deployment Action - 参见可复用工作流 [deploy.yml](.github/workflows/deploy.yml) 6. 创建一个添加或修改已转换 Sigma 规则的 PR，并在 PR 中添加评论 `sigma convert all` 以查看转换和集成过程的实际运行情况 7. 对结果满意后，将 PR 合并到 main，这将触发 deployer 将 Alerting 规则配置到您的 Grafana 实例 8. 随着告警规则的成功配置，为相关文件夹和/或组设置 [Alerting notifications](https://grafana.com/docs/grafana/latest/alerting/configure-notifications/) 以直接联系受影响的用户。或者，您可以将它们连接到 [Grafana IRM](https://grafana.com/docs/grafana-cloud/alerting-and-irm/irm/) 并使用它来管理 on-call 轮换和简化告警路由 ## 常见问题 ### 你们支持哪些 backends/data sources？ 这些 Actions 可以使用 **任何** Sigma backend 转换规则，并为 **任何** data source 生成有效的告警规则，但是，到目前为止，它们仅在 Loki 和 Elasticsearch 上进行了全面测试。特别是，将日志查询转换为度量查询以便它们可以正确地与 Grafana Managed Alerting 一起使用，取决于 backend 是否支持该选项，或者通过使用 `query_model` 选项修改生成的查询。 可以在 Grafana 中使用的相关转换 backends 和 data sources 包括： | Sigma Backend | Data Source | Supported Integration Method | | ------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | ---------------------------- | | [Grafana Loki](https://github.com/grafana/pySigma-backend-loki) | [Loki data source](https://grafana.com/docs/loki/latest/) | Native | | [Elasticsearch](https://github.com/SigmaHQ/pySigma-backend-elasticsearch) | [Elasticsearch data source](https://grafana.com/docs/grafana/latest/datasources/elasticsearch/) | Native | | [Azure KQL](https://github.com/AttackIQ/pySigma-backend-kusto) | [Azure Monitor data source](https://grafana.com/docs/grafana/latest/datasources/azure-monitor/) | Custom Model | | [Datadog](https://github.com/SigmaHQ/pySigma-backend-datadog) | [Datadog data source](https://grafana.com/grafana/plugins/grafana-datadog-datasource/) | Custom Model | | [QRadar AQL](https://github.com/IBM/pySigma-backend-QRadar-aql) | [IBM Security QRadar data source](https://grafana.com/grafana/plugins/ibm-aql-datasource/) | Custom Model | | [Opensearch](https://github.com/SigmaHQ/pySigma-backend-opensearch) | [Opensearch data source](https://grafana.com/grafana/plugins/grafana-opensearch-datasource/) | Custom Model | | [Splunk](https://github.com/SigmaHQ/pySigma-backend-splunk) | [Splunk data source](https://grafana.com/grafana/plugins/grafana-splunk-datasource/) | Custom Model | | [SQLite](https://github.com/SigmaHQ/pySigma-backend-sqlite) | [SQLite data source](https://grafana.com/grafana/plugins/frser-sqlite-datasource/) | Custom Model | | [SurrealQL](https://github.com/SigmaHQ/pySigma-backend-surrealql) | [SurrealDB data source](https://grafana.com/grafana/plugins/grafana-surrealdb-datasource/) | Custom Model | - **Native**: data source 插件受 integrate action 支持，且 query model 是自动生成的。 - **Custom Model**: data source 插件受 integrate action 支持，但 query model 必须作为自定义模型在转换配置中传递。 ### 为什么我不能在告警规则中使用日志查询？ #### 1. Data source 兼容性 Data source 插件对 metric queries 的支持各不相同，convert action 为 Sigma 规则生成的查询通常只会生成 log query，而不是 metric query。相反，转换后的 Sigma Correlation rule 通常会生成 metric query，可以直接在 alert rule 中使用。 - **原生支持**: 一些 data sources，例如 Loki，可以 [对日志查询应用 metric functions](https://grafana.com/docs/loki/latest/query/metric_queries/) - **有限支持**: 其他 data sources，包括 [Elasticsearch data source](https://grafana.com/docs/grafana/latest/datasources/elasticsearch/)，不支持通过其原生查询语言进行 metric queries，但其日志查询响应可以包含 metric 元数据（例如，计数） #### 2. 自定义 query models 对于缺乏原生 metric query 支持的 data sources，您必须使用 `query_model` 配置选项提供自定义 query model（参见 [如何为 data source 使用自定义 query model？](#how-can-i-use-a-custom-query-model-for-a-data-source))。 Query model 是一个 JSON 对象，它定义了用于查询执行的 data source 查询结构。