如何贡献OCSF Schema？开源社区参与指南与贡献流程

如何贡献OCSF Schema开源社区参与指南与贡献流程【免费下载链接】ocsf-schemaOCSF Schema项目地址: https://gitcode.com/gh_mirrors/oc/ocsf-schemaOCSF SchemaOpen Cybersecurity Schema Framework是一个开源的网络安全事件日志和数据标准化框架旨在为不同工具和平台提供一致的安全事件表示方式。本文将详细介绍如何参与OCSF Schema的贡献帮助新手和普通用户快速掌握开源社区的参与方法和贡献流程。为什么要贡献OCSF Schema参与OCSF Schema的贡献不仅能够提升个人在网络安全标准化领域的专业能力还能为全球网络安全社区的发展贡献力量。通过贡献你可以推动网络安全事件数据格式的标准化减少行业内的信息孤岛与全球网络安全领域的专家交流合作提升专业影响力为自己使用的安全工具和平台添加新功能和改进贡献前的准备工作了解OCSF Schema的基本概念在开始贡献之前需要先了解OCSF Schema的一些核心概念字段FieldOCSF中包含的一段数据的唯一标识符名称每个字段还指定了相应的数据类型对象Object一组上下文相关的字段和其他对象的集合也是OCSF中的一种数据类型属性AttributeOCSF中字段和对象的通用名称字段是标量属性而对象是复杂属性事件类Event Class事件由事件类表示事件类是一组特定的属性包括字段和对象表示某个时间点的日志行或遥测提交类别Category对表示特定领域的事件类进行组织更多详细信息可以参考Understanding OCSF。环境准备克隆仓库首先需要将OCSF Schema仓库克隆到本地git clone https://gitcode.com/gh_mirrors/oc/ocsf-schema设置本地开发环境为了验证你的更改建议运行本地的ocsf-server实例。具体设置方法请参考ocsf-server项目文档。贡献流程详解1. Fork仓库首先你需要Fork想要贡献的仓库ocsf-schema、ocsf-docs或ocsf-server。Fork操作会在你的账户下创建一个仓库的副本你可以在这个副本中自由进行修改。2. 进行修改并测试在Fork的仓库中进行所需的更改然后测试确保一切按预期工作且没有错误。测试时本地的ocsf-server实例是必不可少的。添加事件类的步骤如果你想添加一个新的事件类需要遵循以下步骤确定你想要在事件类中添加的所有属性包括字段和对象检查dictionary.json和objects/文件夹你的许多所需属性可能已经存在定义缺失的属性详见下文添加/修改属性部分确定你想要添加事件类的类别并记录其名称在events/文件夹中相应的类别子文件夹内创建一个新文件event_class_name.json可以使用templates/event_class_name.json作为模板定义事件类本身详见下文添加/修改事件类部分最后在本地ocsf-server中验证更改是否按预期工作3. 推送更改到Fork仓库完成修改并测试通过后将更改推送到你的Fork仓库。4. 创建Pull Request创建一个Pull Request将更改合并到主仓库需要至少请求3个审核者。在创建Pull Request时请遵循PR模板中的指南限制单个PR中的提交数量以帮助审核者尽可能明确地说明更改。单个PR必须包含相关的更改每个提交必须包含DCO开发者原产地证书在CHANGELOG.md的Unreleased部分添加条目尽可能详细地描述你的更改确认你已经测试了更改并且服务器运行没有错误检查预览选项卡以确保一切看起来符合预期PR准备好后添加相关标签请求审核者并提交解决拉取请求报告的任何GitHub操作失败和警告并参与对话详细贡献指南添加/修改属性所有OCSF中的可用属性字段和对象都需要在属性字典dictionary.json文件和objects/文件夹中定义如果是定义对象。属性命名约定在添加新属性之前请查看以下OCSF属性约定属性名称必须是有效的UTF-8序列属性名称必须全部小写使用下划线组合单词除下划线外不使用特殊字符除非属性描述历史信息否则使用现在时正确使用单数和复数名称来反映字段内容。例如使用events_per_sec而不是event_per_sec当属性表示多个实体时属性名称应采用复数形式值类型应为数组。例如process.loaded_modules包含多个值——加载的模块名称列表避免重复单词。例如src_endpoint.src_ip应该是src_endpoint.ip尽可能避免缩写。对于公认的缩写可以例外例如ip、os、cve等如何在字典中定义字段要在OCSF中添加新字段需要在dictionary.json文件中定义如下所示uid: { caption: Unique ID, description: The unique identifier. See specific usage., type: string_t }选择一个你想要添加的唯一字段上面示例中的uid并按以下方式填充caption为字段添加一个用户友好的名称description添加简洁的描述来定义属性注意字段描述可以在事件类/对象中重写因此如果是常见字段如name、label、uid等可以添加通用描述特定描述可以在事件类/对象定义中添加type查看OCSF数据类型并确保在定义新字段时使用适当的类型is_array如果你定义的字段是数组需要添加这个布尔键值对例如is_array: true如何定义对象所有可用的对象需要在字典dictionary.json文件中作为单独的字段条目定义并在objects/文件夹中作为不同的.json文件定义查看现有对象确定修改现有对象是否足够或者是否需要一个全新的对象使用templates/object_name.json中提供的模板开始.json文件定义例如vulnerability.json对象文件{ caption: Vulnerability Details, name: vulnerability, description: The vulnerability object describes details related to the observed vulnerability., extends: object, attributes: { desc: { description: The description of the vulnerability, requirement: recommended }, kb_article_list: { requirement: optional } } }caption为对象添加一个用户友好的名称description添加简洁的描述来定义对象extends确保值是object或现有对象例如entityOCSF中的所有对象必须扩展object的基本定义或另一个现有对象name添加对象的唯一名称名称必须与实际.json文件的文件名匹配attributes添加你想要在对象中定义的属性requirement对于每个属性确保添加一个需求值有效值为optional、required、recommended$include你可以包含来自其他地方的属性为此指定一个名为$include的虚拟属性并将其值作为应将其属性贡献给此对象的文件列表相对于模式仓库的根目录注意如果你想创建一个仅作为其他对象基础的对象必须在对象名称和实际json文件名前加上_。生成的对象将不会在OCSF Server中可见。例如查看entity对象。添加/修改事件类所有可用的事件类都在events/文件夹中定义为.json文件查看现有事件类确定修改现有类是否足够或者是否需要一个全新的事件类要定义新类在events/文件夹中相应的类别子文件夹内创建一个新文件event_class_name.json使用templates/event_class_name.json中提供的模板开始json定义uid选择0-99范围内的整数确保该整数在类别内是唯一的没有uid事件类将不会在ocsf-server中可见caption为事件类添加一个用户友好的名称description添加简洁的描述来定义属性name添加事件类的唯一名称确保它与文件名匹配以保持一致性extends确保值是base_eventattributes添加你想要在事件类中定义的属性group对于每个属性确保添加一个组值有效值为classification、context、occurrence、primaryrequirement对于每个属性确保添加一个需求值有效值为optional、required、recommended$include与对象一样你也可以包含来自其他地方的属性为此指定应将其属性贡献给此对象的文件列表相对于模式仓库的根目录constraints对于每个类你可以添加对属性要求的约束有效的约束类型是at_least_one、just_one弃用属性要弃用属性字段、对象请按照以下步骤操作创建一个GitHub issue解释为什么需要弃用某个属性以及替代解决方案是什么利用以下标志允许属性的弃用这个标志需要添加到作为弃用主题的属性的json属性中deprecated: { message: Use the code ALTERNATE_ATTRIBUTE /code attribute instead., since: semver }验证更改贡献者应在提交PR之前验证更改测试和验证更改的最佳方法是运行ocsf-server的本地实例。按照这里的说明设置你自己的本地ocsf-server。如果新做的更改有任何问题服务器将抛出相应的错误。在提交更改之前解决这些错误你的服务器运行应该完全没有错误。开发者原产地证书 (DCO)通过为此项目做出贡献我证明(a) 贡献完全或部分由我创建并且我有权根据文件中指示的开源许可证提交它或者(b) 贡献基于先前的工作据我所知该工作受适当的开源许可证保护并且我有权根据该许可证提交该工作无论全部或部分由我创建的修改在同一开源许可证下除非我被允许在不同的许可证下提交如文件中所示或者(c) 贡献是由其他认证(a)、(b)或(c)的人直接提供给我的并且我没有修改它。(d) 我理解并同意此项目和贡献是公开的并且贡献的记录包括我提交的所有个人信息包括我的签名将无限期保留并可能根据此项目或所涉及的开源许可证进行重新分发。我们要求对此存储库的每一次贡献都使用开发者原产地证书进行签名。此外请使用你的真实姓名。我们不接受匿名贡献者或使用假名的贡献者。每个提交必须包含如下所示的DCOSigned-off-by: Jane Smith jane.smithemail.com你可以在编写提交消息时自己输入这行。但是如果你的user.name和user.email在git配置中设置你可以使用-s或--signoff将Signed-off-by行添加到提交消息的末尾。OCSF扩展OCSF Schema可以通过添加扩展来扩展该扩展定义其他属性、对象、配置文件、事件类和/或类别。扩展允许创建特定于供应商/客户的模式或扩充现有模式以更好地满足自定义要求。扩展也可用于排除非必要的模式域使核心模式保持简洁。扩展使用与新模式相同的框架可选地从字典创建类别、配置文件或事件类。与类别和事件类一样扩展在框架内具有唯一的ID以及它们自己的版本控制。以下部分提供了在OCSF中创建扩展的指南。为你的扩展保留UID和名称为了保留ID空间并使你的扩展公开请在OCSF扩展注册表这里中为你的扩展添加唯一标识符和唯一名称。这样做是为了避免与核心或其他扩展模式冲突。创建扩展的子目录要扩展模式请在extensions目录中创建一个新的子目录并添加一个新的extension.json文件该文件定义扩展的name和uid。例如{ caption: New Extension, name: new_ex, uid: 123, version: 0.0.0 }扩展的目录结构与顶级模式目录相同根据所需的扩展类型它可能包含以下文件和子目录名称描述categories.json创建它来定义新类别。注意为了避免与核心模式中定义的类别冲突类别ID必须大于或等于30dictionary.json创建它来定义新属性。events创建它来定义新事件类。objects创建它来定义新对象。profiles创建它来定义新配置文件。作为参考可以查看当前添加到OCSF的Linux Extension。总结通过本文的指南你应该已经了解了如何为OCSF Schema项目做出贡献的基本流程和方法。无论是添加新的事件类、对象还是修改现有属性都需要遵循项目的贡献规范和最佳实践。记住在提交PR之前一定要充分测试你的更改确保它们符合项目的要求。OCSF Schema社区欢迎所有愿意为网络安全标准化做出贡献的人你的每一个贡献都将帮助改进这个框架使其更好地服务于整个网络安全行业。如果你在贡献过程中遇到任何问题可以通过Community Discussions或Slack Workspace寻求帮助。祝你贡献顺利期待在OCSF Schema的贡献者列表中看到你的名字【免费下载链接】ocsf-schemaOCSF Schema项目地址: https://gitcode.com/gh_mirrors/oc/ocsf-schema创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考