kubescape/rulelibrary

# Kubescape 规则库 Kubescape 的 CEL (Common Expression Language) 运行时威胁检测规则库。此仓库包含一组安全规则，可用于 Kubernetes 环境中的运行时威胁检测。 ## 概述 规则库提供了一种使用 YAML 格式定义安全规则的结构化方法。每个规则都定义为一个 Custom Resource Definition (CRD) 实例，可以部署到 Kubernetes 集群中进行运行时威胁检测。 ## 规则格式 每个规则都定义在一个 YAML 文件中，结构如下： ``` apiVersion: kubescape.io/v1 kind: Rules metadata: name: rule-name-rule namespace: kubescape labels: app: kubescape spec: rules: - name: "Rule Display Name" enabled: true id: "R####" description: "Description of what the rule detects" expressions: message: "CEL expression for alert message" uniqueId: "CEL expression for unique identifier" ruleExpression: - eventType: "eventType_name" expression: "CEL expression for detection logic" profileDependency: 0 # 0=Required, 1=Optional, 2=NotRequired severity: 1 supportPolicy: false tags: - "tag1" - "tag2" ``` ### 规则字段 | 字段 | 类型 | 描述 | 必填 | |-------|------|-------------|----------| | `name` | string | 人类可读的规则名称 | 是 | | `enabled` | boolean | 规则是否激活 | 是 | | `id` | string | 唯一规则标识符 (格式: R####) | 是 | | `description` | string | 规则的详细描述 | 是 | | `expressions.message` | string | 用于警报消息的 CEL 表达式 | 是 | | `expressions.uniqueId` | string | 用于唯一事件 ID 的 CEL 表达式 | 是 | | `expressions.ruleExpression` | array | 检测表达式的数组 | 是 | | `profileDependency` | integer | Profile 依赖级别 (0,1,2) | 是 | | `severity` | integer | 规则严重级别 | 是 | | `supportPolicy` | boolean | 规则策略是否支持该规则 | 是 | | `tags` | array | 用于分类的标签数组 | 是 | | `state` | object | 规则状态 | 否 | ### 上下文标签 `tags` 列表包含机器可读的 `context:*` 标签，可帮助代理决定规则应在何处运行。上下文标签是累加而非互斥的，因此当行为在多种环境中有意义时，单个规则可以带有多个标签。 | 上下文标签 | 含义 | |-------------|---------| | `context:host` | 该行为从宿主机的角度来看是有意义的，例如宿主机进程或宿主机挂载的资源。 | | `context:container` | 无论使用哪种编排器，该行为在容器边界处都是有意义的。适用于应在 Kubernetes、ECS 或独立容器代理中运行的规则。 | | `context:kubernetes` | 该规则在 Kubernetes 部署中有效。为了与旧代理向后兼容，请在容器规则上保留此标签；对于 Kubernetes 特有的信号（如 `kubectl exec`、`port-forward` 或服务账号行为），请单独使用此标签。 | 示例： - R0010 带有 `context:host` 和 `context:container`，因为对 `/etc/shadow` 的访问从宿主机工作负载或从能够看到该文件的容器来看可能都是有意义的。 - R2000 和 R2001 仍然仅限 Kubernetes，因为它们由 Kubernetes API 活动驱动，而不是通用的容器行为。 每个规则 README 中的 `Platforms` 行是面向人类的文档。`context:*` 标签是路由元数据，因此它们经常重叠但不可互换。 ### 支持的事件类型 - `exec` - 进程执行事件 - `open` - 文件访问事件 - `capabilities` - Linux capability 事件 - `dns` - DNS 查询事件 - `network` - 网络连接事件 - `syscall` - 系统调用事件 - `randomx` - XMRig 挖矿事件 - `symlink` - 符号链接事件 - `hardlink` - 硬链接事件 - `ssh` - SSH 连接事件 - `http` - HTTP 请求事件 - `ptrace` - 进程跟踪事件 - `iouring` - IO_uring 事件 - `fork` - 进程 fork 事件 - `exit` - 进程退出事件 - `procfs` - Proc 文件系统事件 ## 编写规则 ### 1. 创建规则目录 按照以下命名约定在 `pkg/rules/` 中创建一个新目录： ``` r####-descriptive-name/ ``` 示例： ``` pkg/rules/r0001-unexpected-process-launched/ ``` ### 2. 创建规则 YAML 文件 在您的规则目录中创建一个包含规则定义的 YAML 文件（参见示例 [unexpected-process-launched.yaml](pkg/rules/r0001-unexpected-process-launched/unexpected-process-launched.yaml)) ### 3. 添加测试用例 在您的规则目录中创建一个 `rule_test.go` 文件（参见示例 [rule_test.go](pkg/rules/r0001-unexpected-process-launched/rule_test.go)) ### 4. 测试您的规则 运行测试以确保您的规则正常工作： ``` go test -v ./pkg/rules/r0001-unexpected-process-launched/ ``` ## 规则生成脚本 `gen.sh` 脚本会自动将所有单独的规则 YAML 文件合并为一个 CRD 实例。推荐的入口点是下方的 Make 目标，它封装了该脚本。 ### 用法 ``` make generate-rules-crd ``` ### 它的工作原理 1. **扫描** `pkg/rules/` 目录中的所有 YAML 文件 2. **合并** 所有单独的规则定义为一个单独的 Rule 实例 3. **生成** `rules-crd.yaml`，其中 spec 数组包含所有规则 4. **验证** 生成的 YAML（如果 `yq` 可用） ### 输出 该脚本生成的 `rules-crd.yaml` 包含： ``` apiVersion: kubescape.io/v1 kind: Rules metadata: name: kubescape-rules namespace: kubescape labels: app: kubescape spec: rules: - name: "Rule 1" # ... rule 1 definition - name: "Rule 2" # ... rule 2 definition # ... all other rules ``` ### 前置条件 - `bash` shell - `yq`（可选，用于 YAML 验证） ## 开发工作流 1. 遵循目录结构和命名约定**创建新规则** 2. 使用正确的 CEL 表达式**编写规则 YAML** 3. 在 `rule_test.go` 中**添加全面的测试** 4. 使用 `go test -v ./pkg/rules/your-rule/` **测试您的规则** 5. 使用 `make generate-rules-crd` **生成合并后的 CRD** 6. 将生成的 `rules-crd.yaml` **部署**到您的 Kubernetes 集群 ## 测试 ### 运行所有测试 ``` go test -v ./pkg/rules/... ``` ### 运行特定规则测试 ``` go test -v ./pkg/rules/r0001-unexpected-process-launched/ ``` ### 测试生成脚本 ``` make generate-rules-crd # 检查生成的 rules-crd.yaml 文件 ``` ## CEL 表达式 规则使用 Common Expression Language (CEL) 编写表达式。核心概念： ### 消息表达式 定义警报消息格式： ``` "'Unexpected process launched: ' + event.Comm + ' with PID ' + string(event.Pid)" ``` ### 唯一 ID 表达式 创建用于去重的唯一标识符： ``` "event.Comm + '_' + string(event.Pid) + '_' + event.ExePath" ``` ### 规则表达式 定义检测逻辑： ``` "!data.profile_checks.exec_path" ``` ## 最佳实践 1. 为规则和目录**使用具有描述性的名称** 2. **遵循 ID 编号约定** (R####) 3. 为每个规则**编写全面的测试** 4. **使用适当的标签**进行分类 5. 根据影响**设置正确的严重级别** 6. **使用注释记录复杂的 CEL 表达式** 7. **测试正反两种场景** 8. 在部署前**验证生成的 YAML** ## 声明 `profileDataRequired` 当规则的 `profileDependency` 为 `Required` (0) 或 `Optional` (1) 时，它必须声明 `profileDataRequired`，列出该规则在运行时查询的 profile 接口。请检查每个将事件字段传递给 profile 助手（`ap.*` / `nn.*`）的 CEL 守卫，并将参数转换为正确 surface key 下的模式： | 事件字段 | Surface key | |---|---| | `event.path` / `event.exepath` (open 事件) | `opens` | | `event.path` / `event.exepath` (exec 事件) | `execs` | | `event.syscallName` | `syscalls` | | `event.capName` | `capabilities` | | `event.name` (DNS) | `egressDomains` | | `event.dstAddr` / `event.dstIp` (network) | `egressAddresses` | | `event.endpoint` (HTTP) | `endpoints` | | 守卫操作符 | 模式类型 | |---|---| | `==` | `exact` | | `.startsWith(...)` | `prefix` | | `.endsWith(...)` | `suffix` | | `.contains(...)` | `contains` | 如果助手接收到一个完全动态的参数且没有共置的文字守卫，请将该 surface 声明为 `all`。 示例： ``` profileDependency: 0 profileDataRequired: opens: - exact: "/var/run/docker.sock" - prefix: "/etc/cron.d/" execs: all ``` 位于 `cmd/lint-projection/` 的 lint 工具会强制要求声明存在且符合 schema 规范。使用 `make lint-projection` 在本地运行它。确保模式正确是规则作者的责任——部署后，node-agent 中的运行时指标会捕获偏差。 `profileDependency: 2` (NotRequired) 的规则**不得**声明 `profileDataRequired`；如果声明了，lint 会发出警告。 ## 贡献 1. Fork 该仓库 2. 创建一个功能分支 3. 按照指南添加您的规则 4. 编写全面的测试 5. 运行生成脚本 6. 提交 pull request

标签：AMSI绕过, CEL, EVTX分析, Kubescape, 威胁检测, 应用安全, 日志审计