deadparrot610/yara-rules-management

# YARA 规则管理与构建流水线 这是一个用于组织 YARA 检测规则的版本控制中心和 CI/CD 流水线。它管理供应商提供的、内部自定义的以及覆盖规则；应用声明式过滤策略；并在每次更改时将所有内容编译成一个经过验证的、可部署的单一规则集。 ## 此仓库的功能 检测工程师将规则提交到三个目录树之一，在清单中声明覆盖，并声明过滤策略。每次更改时，流水线会： 1. **Lint** 每个规则文件（语法、必需的元数据）并验证过滤策略。 2. **构建** 单一规则集 —— 合并三个来源，移除被覆盖的供应商规则，应用过滤策略，并**将编译结果作为验证关卡**。 3. **测试** 构建好的规则集与静态测试固件的匹配情况，断言预期匹配和不匹配项，并设有误报复检关卡。 4. 可选地**扫描已上传的 PCAP**（手动作业）。 5. 在发布标签上**打包**带有版本号的、可下载的构建产物。 流水线负责生成产物；将它们部署到检测平台是一个独立的、超出范围的过程。 ## 核心概念 **三种规则类别。** *供应商* (Vendor) 规则是从第三方获取的一个或多个 `.yara` 文件，并按原样提交。*自定义* (Custom) 规则由内部编写。*覆盖* (Overrides) 规则是用于替换特定供应商规则的内部规则。 **覆盖意味着移除。** YARA 拒绝在一个编译单元中存在两个具有相同标识符的规则，而可部署的输出是一个单一单元。因此，覆盖供应商规则并不意味着将你的规则与原规则一起发布——这意味着构建过程会**移除**指定的供应商规则，并用你的替换规则取而代之。每个覆盖替换了哪些供应商规则会在 `rules/overrides/override_manifest.yaml` 中显式声明，这既为了保证移除操作的确定性，也为了保留审计追踪。如果覆盖指向了一个已不存在的供应商规则（即*过期的覆盖*），构建将会失败。 **过滤器是一个选择层。** 过滤策略 (`filters/filter_policy.yaml`) 决定合并语料库中的哪些规则可以输出到最终结果中——可以全局设定、针对每个源规则集设定，或针对单个规则设定。它从不删除源规则；被过滤掉的规则仍保留在仓库中，可以通过修改策略重新包含。构建过程会防范各种微妙的失败模式（例如：过滤掉覆盖规则会导致防护盲区；排除某个被现存规则所引用的规则会导致编译失败；过于狭窄的白名单会导致最终发布的规则数量极少）。 ## 仓库结构 ``` . ├── docs/ # design documents (PRD, ARCHITECTURE, DECISIONS, IMPLEMENTATION_PLAN) ├── config/build.yaml # output formats, YARA modules, external vars, policy flags ├── rules/ │ ├── vendor/*.yara # vendor rules (one or more files), committed as received │ ├── custom/ # in-house rules, grouped by category │ └── overrides/ │ ├── overrides.yara # replacement rules │ └── override_manifest.yaml # which vendor rules each override supersedes + why ├── filters/filter_policy.yaml # include/exclude selection layer ├── scripts/ │ ├── build_ruleset.py # parse → strip → merge → filter → order → compile → manifest │ ├── lint.py # per-file syntax + metadata + filter-policy validation │ ├── check_overrides.py # stale-override / conflict detection │ └── apply_filters.py # filter resolution + cross-checks (+ preview mode) ├── tests/ # pytest harness, declarative cases, inert fixtures └── dist/ # build output (gitignored; produced by the build) ``` ## 快速开始 需要 Python 3 以及本地安装的 YARA。 ``` pip install -r requirements.txt # plyara, yara-python, pytest, pyyaml python scripts/build_ruleset.py # build dist/merged_rules.yara and the manifest pytest tests/ # run the test suite against the built ruleset ``` 构建输出会生成在 `dist/` 目录中：`merged_rules.yara`（源文件）和 `build_manifest.json`（包含按来源分类的规则计数、被覆盖的内容、被过滤的内容及其对应的过滤器，以及输入哈希值）。 ## 常见任务 **添加自定义规则。** 将 `.yara` 文件放入相应的 `rules/custom/` 子目录中。必须包含必需的元数据（作者、日期、描述、参考、严重程度），否则 Lint 检查会拒绝它。 **覆盖供应商规则。** 将你的替换规则添加到 `rules/overrides/overrides.yara`，然后在 `rules/overrides/override_manifest.yaml` 中声明它替换了哪些规则： ``` overrides: - override_rule: Custom_Override_Emotet supersedes: [Vendor_Emotet_Generic, Vendor_Emotet_v2] reason: "Vendor rule fires on internal packer; condition tightened." ticket: SEC-1234 author: a.analyst date: 2026-05-30 ``` **更新供应商文件。** 在 `rules/vendor/` 下添加、替换或删除文件，然后提交合并请求（MR），以便在合并前运行差异比较和过期覆盖检查。如果供应商更新删除了你正在覆盖的规则，这将表现为一个过期的覆盖。 **从输出中过滤掉某个规则。** 在 `filters/filter_policy.yaml` 中添加条目。你可以将其作用域设为 `global`、某个规则集（`vendor`/`custom`/`overrides`），或单个 `rule:`： ``` filters: - id: F-003 scope: rule:Custom_Noisy_Rule action: exclude reason: "FP storm pending tuning" ticket: SEC-2002 ``` 在提交之前预览策略更改将包含或排除哪些内容： ``` python scripts/apply_filters.py --preview ``` ## CI/CD 流水线 运行在包含 YARA 和 Python 依赖的固定版本 Docker 镜像上。 | 阶段 | 触发条件 | 目的 | |---|---|---| | `lint` | 每次 push / MR | 针对单个文件编译、元数据 schema、过滤策略 schema | | `build` | 每次 push / MR | 合并、应用过滤器、编译、输出清单 → `dist/` 构建产物 | | `test` | 每次 push / MR | 扫描测试固件、断言匹配/不匹配项、误报复检关卡 (JUnit) | | `pcap-test` | 手动触发 | 使用构建好的规则集扫描已上传/指定的 PCAP（或提取的文件） | | `package` | 基于标签触发 | 将带有版本号的规则集和清单发布到 Package Registry | 损坏的规则、过期的覆盖、导致防护盲区的过滤器或误报匹配都会导致流水线失败。 ## 设计文档 | 文档 | 目的 | |---|---| | [PRD.md](docs/PRD.md) | 需求（功能需求 FR-1…FR-24，非功能需求 NFR-1…7）、范围、验收标准。 | | [ARCHITECTURE.md](docs/ARCHITECTURE.md) | 技术设计：覆盖模型、过滤策略模型、构建顺序、CI 设计、工具链。 | | [DECISIONS.md](docs/DECISIONS.md) | 决策 (D-1…D-11) 及决策日志；待定项为 D-3 和 D-6。 | | [IMPLEMENTATION_PLAN.md](docs/IMPLEMENTATION_PLAN.md) | 分阶段构建顺序，以及每个阶段的完成标准。 | ## 维护者注意事项 - `config/build.yaml` 和 `filters/filter_policy.yaml` 是关于模块、外部变量、输出格式和选择策略的唯一数据源——代码会动态读取它们，而不是进行硬编码。 - 编译步骤是权威的验证关卡；任何未通过编译的内容都不会被输出。 - 所有关键决策均已确定——完整日志请参阅 [docs/DECISIONS.md](docs/DECISIONS.md) §3。目前还有两个待定项：PCAP 交付机制 (D-3) 和测试样本获取方式 (D-6)，这两项目前都有可用的默认方案。

标签：YARA, 云资产可视化, 安全规则引擎, 恶意代码分类, 构建流水线, 规则管理, 请求拦截, 逆向工具