ocsf/ocsf-validator

# OCSF Schema Validator 一个用于验证 [OCSF 模式](https://github.com/ocsf/ocsf-schema) 贡献的工具，旨在防止在贡献模式时出现人为错误，以保持模式可被机器读取。 OCSF 提供了多种包含机制以促进复用，但这意味着单个模式文件可能不完整。这使得使用现成的模式定义工具进行验证变得复杂。 [查询](https://www.query.ai) 是一个将异构安全数据规范化为 OCSF 的联邦式搜索解决方案。该验证器借鉴了 Query 团队编写的活跃代码和文档生成工具。 ## 快速开始 ### 先决条件 - Python >3.11 - pip - [OCSF 模式](https://github.com/ocsf/ocsf-schema) 的副本 ### 安装 你可以使用 `pip` 安装验证器： ``` $ pip install ocsf-validator ``` ## 用法 你可以针对你正在工作的模式副本运行验证器，以在提交拉取请求之前识别问题。调用验证器使用 `python` 并提供工作副本根目录的路径。 示例： ``` $ python -m ocsf_validator . $ python -m ocsf_validator ../ocsf-schema ``` ## 测试 验证器会对模式副本执行以下测试： - 模式可读且所有 JSON 有效。[致命错误] - 目录结构符合预期。[警告] - `$include`、`profiles` 和 `extends` 指令中的目标可被找到。[错误] - 所有必需属性在模式定义文件中存在。[警告] - 模式定义文件中没有未识别的属性。[警告] - 所有属性在属性字典中均被使用。[警告] - 同一记录类型内没有名称冲突。[警告] - 所有属性均在属性字典中定义。[警告] 如果任何错误或致命测试失败，验证器将以非零退出码退出。 ## 技术概述 OCSF 元模式通过文件路径表示为记录类型，实现方式如下： 1. 记录类型使用 Python 的类型系统表示，在 `types.py` 中将其定义为 Python `TypedDict`。这使验证器可以利用 Python 的反射能力。 2. 文件和记录类型通过匹配文件路径的模式进行关联。这些模式在 `matchers.py` 中命名，以便类型检查器捕获错误。 3. 类型在 `type_mapping.py` 中映射到文件路径模式。 待验证的 OCSF 模式内容主要由 `reader.py` 中定义的 `Reader` 表示。`Reader` 从源（通常来自文件系统）加载要验证的模式定义并原样包含它们。`processor.py` 中的 `process_includes` 函数及其他内容通过应用 OCSF 的各种包含机制来变更 `Reader` 的内容。 验证器定义在 `validators.py` 中，用于测试模式内容是否存在各种问题。验证器应将 `Exception` 传递给 `errors.py` 中定义的特殊错误收集器。该模块还定义了多种表示问题模式状态的自定义异常类型。`Collector` 默认抛出错误，但也可以暂存错误，直到被更大的验证过程（例如 `ValidationRunner`）聚合。 `ValidationRunner` 将上述所有构建块组合在一起，从文件系统读取提议的模式，验证模式，并在遇到错误时提供有用的输出和非零退出码。

标签：CLI 工具, JSON Schema, OCSF, Python 工具, Python 验证器, Query, Schema 校验, 元数据验证, 包含引用校验, 命名冲突检测, 安全数据标准化, 安全数据规范化, 安全贡献, 属性完整性校验, 模式工具, 模式校验, 模式验证, 目录结构校验, 逆向工具, 预提交检查