网络安全【免费下载链接】suricataSuricata is a network Intrusion Detection System, Intrusion Prevention System and Network Security Monitoring engine developed by the OISF and the Suricata community.项目地址https://gitcode.com/gh_mirrors/su/suricata点击查看免费下载本指南围绕 Suricata 官方开发者文档 contribution-process.rst 展开系统讲解社区开发者向 Suricata 提交补丁patch或补丁集patchset时需要遵循的完整流程从签署贡献协议、认领 Ticket、选择工作分支到编码与文档风格、Commit 规范、提交 Pull Request、应对评审反馈直至合并后的收尾清理。读完本文你将掌握一条可直接落地的贡献路线图并了解仓库中与之对应的规范文件、CI 配置与测试要求从而以符合 Suricata 团队预期的方式提交高质量代码。贡献流程总览十步路线图Suricata 官方文档将一次完整的贡献概括为以下十个步骤阅读并签署 贡献协议Contribution Agreement尽早沟通使用团队偏好的 沟通渠道认领claim或开启一个 Ticket从main分支出发创建自己的分支遵循项目的 编码风格遵循项目的 文档风格遵守 Commit 规范在 Pull Request 中附加版本号将 评审反馈 融入新的 PR合并后 收尾清理Wrap up。下文将逐项展开说明。仓库根目录的 .github/CONTRIBUTING.md 也给出了同一流程的高层概括自动化的构建与单元测试 → 团队与社区评审 → 团队触发的 QA 运行。贡献协议与知识产权归属在开始任何贡献之前必须先审阅并签署 Suricata 的贡献协议Contribution Agreement这被文档标记为 Important!。签署该协议的目的是把 Suricata 的代码所有权保留在单一主体——Open Information Security FoundationOISF手中从而保证项目在开源许可框架下的长期可维护性。仓库中的 .github/CONTRIBUTING.md 明确说明在接收你的 Pull Request 之前我们需要你或你的组织签署贡献协议。同时.github/PULL_REQUEST_TEMPLATE.md 的 PR 模板也将我已签署 OISF 贡献协议列为提交前的必选检查项并注明该协议只需签署一次。沟通是第一步无论是澄清疑问、讨论或提议新功能、报告 bug 与优化点还是寻求帮助提前沟通都至关重要。Suricata 社区的主要沟通渠道包括官方 issue 跟踪器Redmine用于跟踪 bug、功能请求与开发任务开发者论坛面向开发者的讨论区Discord 服务器实时沟通包括专门的开发者频道。仓库中的文档、CI 配置与源码都以团队协作为前提例如.github/workflows/下的 builds.yml 等自动化工作流就是为评审与 QA 流程服务的。认领或开启 Ticket对于功能与 bug团队需要 Ticket 来跟踪工作进度并判断变更是否需要 backport 到稳定分支。Ticket 的意义在于它记录你的想法便于团队分析其是否契合 Suricata 的路线图功能被接受后团队可以据此跟踪进度。Ticket 标题规范Ticket 的标题必须清晰反映问题本身按跟踪器的类型例如[Bug #00000] stream: segfault in case of increasing gaps——标明受影响的子系统stream与具体 bug 现象[Bug #19999] dcerpc: memleak in case of invalid data——直接描述 bug 本身[Bug #44444] stream: excess memuse in TcpTracking——标题点到为止准确传达问题。重要提示Ticket 标题会用于每次发布时自动生成 ChangeLog仓库根目录的 ChangeLog 即其产物。如果标题含糊不清ChangeLog 就无法准确传达某个版本修复了哪些问题。因此好的标题就是好的发布记录。新功能需要先征询团队意见如果你想添加全新功能例如一个新的应用层协议请先询问团队是否计划将其合并进 Suricata。这能让双方明确新功能在路线图中的位置避免把时间与热情浪费在可能不被接受的贡献上。因此在动手写任何代码之前先在 Ticket 或讨论渠道上征求团队意见。对于真正琐碎的修复或清理trivial fixes/cleanups则不需要 Ticket。认领 Ticket一旦问题被确认可以动手将 Ticket 分配给自己这需要你拥有 developer 角色可以在 Ticket 上直接申请或在 Discord 开发者频道说明你感兴趣处理某个编号的 Ticket如果提交的 PR 对应一个未分配给自己的 Ticket团队可能直接关闭 PR 并要求你先完成认领。所以请先沟通在 Ticket 下留言并自行分配如果 Ticket 已被他人认领请先在 Ticket 上或私下联系对方征得同意后再介入。期望与社区支持功能如果提交的新功能不属于 Suricata 的核心功能范畴它将被标记为community supported社区支持状态。由于 Suricata 开发团队规模精干对于这类功能团队在批准前期望贡献者或其赞助组织作出一定承诺新贡献需附带一组Suricata-Verify 测试必要时还包括单元测试通过后方可批准若贡献用于替换现有功能需提供与既有关键字/功能兼容的证明功能获批后你需要持续维护它——如果你无法维护需有其他社区成员接手。无论贡献规模大小或复杂程度如何团队都期望贡献者尊重上述指南与流程。社区支持与维护一个功能的含义community supportedSuricata 团队会尽量少花时间在这些功能上以便聚焦核心功能若你无法承诺支持请提前说明团队或社区成员可以据此考虑提供帮助——最好在实际动手前说明因为如果无人接手团队会拒绝该功能。社区支持功能默认禁用如果它引入新的依赖库或 Rust crate这些依赖也必须是可选的且默认禁用。支持maintain一个功能意味着实际维护它修复 bug、编写文档、保持其与主分支同步更新、通过论坛和/或 Discord 提供最终用户支持。失效 Ticket 策略志愿者的可用性与兴趣可能随时间变化。为防止 Ticket 长期无人处理Suricata 有一条明确的政策如果某个 Ticket 在 6 个月内没有任何贡献更新团队将取消unclaim该 Ticket。如果你认领了 Ticket 但后来发现自己无法继续请在 Ticket 中告知并取消认领这样所有人都会知道工作仍然开放、等待有人接手。在哪个分支上工作仓库通常同时存在 23 个活跃分支带版本号的稳定分支例如main-7.0.x、main-8.0.xmain开发分支。稳定分支只应用于重要的 bug 修复或必要的 backport主要面向经验更丰富的贡献者新功能或大规模重构则在开发分支main上进行。新开发者与新的开发工作应使用main除非有非常特殊的情况——这种特殊情况应事先与团队讨论。如有疑问可通过 沟通渠道 联系团队。仓库中的 backports-guide.rst 给出了当前分支格局的实例main如 9.0.0-dev、main-8.0.x主稳定版、main-7.0.x旧稳定版并详细说明了 backport 的选取原则安全修复、bug 修复以及少数有充分理由的功能 backport与git cherry-pick -x commit-hash等操作流程可供对照参考。获取代码时可从本仓库克隆git clone https://gitcode.com/gh_mirrors/su/suricata创建自己的分支创建描述性的分支名很有价值。例如你在处理 Ticket 123改进 GeoIP 功能可以命名分支为geoip-feature-123-v1。其中-v1是为反馈迭代预留的每次吸收反馈都要为新的 PR 创建新分支。处理第一轮反馈时在geoip-feature-123-v2上工作以此类推。编码风格所有代码都必须遵循仓库中的 Coding Style即 code-style.rst。其核心要求包括格式化C 代码使用clang-format要求 clang 9 或更新版本CI 目前用 clang-format-14 校验推荐使用git clang-format仅格式化你的改动也可使用仓库自带的 scripts/clang-format.sh 封装脚本行长限制在 100 字符内续行缩进至少 8 空格缩进4 空格缩进函数参数、循环、if 语句换行用 8 空格缩进变量定义换行用 4 空格大括号函数开括号另起一行控制语句与结构体/枚举开括号同行else与前后大括号同行cuddled else命名函数名形如SCNamedLikeThis()非静态函数一律加SC前缀变量全小写下划线宏全大写结构体与 typedef 用 TitleCase 且在头文件暴露时加SC前缀注释函数用 Doxygen 注释普通注释偏好/* */风格禁用函数如strtok、sprintf、strcpy等需用strtok_r、snprintf、strlcpy等替代Rust 代码遵循 Rust 风格并用rustfmt格式化通过#[no_mangle]暴露给 C 的 FFI 函数须遵循 C 命名风格。例如src/decode-ethernet.c中的以太网解码函数就是符合上述风格的典型实现int DecodeEthernet(ThreadVars *tv, DecodeThreadVars *dtv, Packet *p, uint8_t *pkt, uint16_t len, PacketQueue *pq) { SCPerfCounterIncr(dtv-counter_eth, tv-sc_perf_pca); if (unlikely(len ETHERNET_HEADER_LEN)) { ENGINE_SET_INVALID_EVENT(p, ETHERNET_PKT_TOO_SMALL); return TM_ECODE_FAILED; } ... return TM_ECODE_OK; }文档风格对于代码本身的文档按贡献内容分别遵循 Rust 文档规范或 Doxygen 规范。而用户指南与开发者指南即本类文档采用reStructuredText编写并用Sphinx渲染。写作规范如下每行文本在 79 字符处换行最多 80 字符添加图表或图片时优先使用可以自动生成的替代方案例如 mscgen 时序图、drawio 等仓库 doc/userguide/devguide/extending/app-layer/diagrams/ 下即存放了可自动生成的.msc源文件与对应 PNG文档会发布到 Read the Docs 并可构建为 PDF因此排版需兼顾这两种格式。标题层级reStructuredText 允许灵活定义标题符号为保证一致性请按以下顺序使用符号级别#h1*h2h3-h4~h5^h6示例Page Title ########## Section ******* Sub-Section Rule examples -------------规则示例容器example-rule编写规则文档时项目提供了专门的容器example-rule可将规则呈现为更易读的字体框并支持高亮签名中的特定元素example-rule-action高亮动作部分example-rule-header高亮规则头协议、地址、端口、方向example-rule-options高亮选项部分example-rule-emphasis强调自定义片段。使用方式先用.. role:: example-rule-role声明角色每篇文档只需声明一次再用反引号包裹要高亮的片段。例如.. container:: example-rule :example-rule-action:alert :example-rule-header:http $HOME_NET any - $EXTERNAL_NET any :example-rule-options:(msg:HTTP GET Request Containing Rule in URI; flow:established,to_server; http.method; content:GET; http.uri; content:rule; fast_pattern; classtype:bad-unknown; sid:123; rev:1;)强调用法示例.. container:: example-rule alert ssh any any - any any (msg:match SSH protocol version; :example-rule-emphasis:ssh.proto; content:2.0; sid:1000010;)Commit 规范与提交消息提交 PR 之前请先阅读 code-submission-process.rst 中的 Commit 规范核心要求如下逻辑分离Commit 之间要逻辑独立不要在一个 commit 里混入无关的修复避免冗余如果 commit 2 只是修复 commit 1 的问题应将它们 squash 合并消息要解释非平凡内容一个 commit 不要同时修改 重命名/移动代码这些应拆分为独立 commit代码改变或新增行为时相关的文档更新放独立 commit但两个 commit 消息中要带上同一个 Ticket 编号消息格式有意义的主题行≤50 字符后跟空行主题行用子系统前缀命名如rule parsing: fixing foobar不确定前缀时参考你 PR 中文件的既往提交历史描述部分按 ~72 字符换行每个 commit 都应可单独编译从最早的 commit 起作者格式FirstName LastName nameexample.com。仓库提供了现成的 commit 消息模板可通过如下命令启用git config commit.template /path/to/suricata/git-template/commit-template.txt模板内容见 git-templates/commit-template.txt它引导提交者填写标题、描述为什么做这个改动与 Ticket 编号。Commit 消息中还应视情况包含修复的 Ticket如 Fixes Bug #123.、处理的编译器告警、Coverity Scan 问题、静态分析器cppcheck/scan-build 等错误。下面是一个官方示例pcap/file: normalize file timestamps Normalize the timestamps that are too far in the past to epoch. Bug: #6240.提交 Pull RequestPull Request 本质上是指向你仓库中某个分支的指针GitHub 的评审界面即用于此。相关的完整流程见 github-pr-workflow.rstPR 标准见 code-submission-process.rst。版本号与分支纪律一个分支只能用于单个PRPR 提交后不应再更新该分支PR 必须有良好的描述若关联 Ticket须附上 issue 跟踪器链接增量 PR新迭代必须链接到上一轮 PR并描述自上一版以来的变更关联 PR 中要处理的 Ticket修复 issue 时提交 PR 后应将 issue 状态更新为 In Review改变或新增功能的 PR 应包含文档更新 commit。自动化 CI 与 QAPR 提交后会自动运行 GitHub-CI 集成检查构建检查、suricata-verify 与单元测试相关配置见 .github/workflows/builds.yml。一般几分钟内即可完成如果测试失败PR 不会被考虑所以提交后要留意检查结果并在失败的 PR 上处理或询问。合并前团队还会在私有 QA 实验室执行其他集成测试即使 GitHub-CI 已通过这些测试失败也可能要求进一步修改。仓库中的 .github/PULL_REQUEST_TEMPLATE.md 列出了一份完整的提交前清单包括已阅读贡献指南、已签署贡献协议、已更新用户指南doc/userguide/、已更新 JSON schemaetc/schema.json、已创建 Ticket 等还预留了SV_REPO/SV_BRANCH、SU_REPO/SU_BRANCH变量用于在 CI 中指向对应的 Suricata-Verify / Suricata-Update 分支。PR 评审工作流Draft PR若 PR 不打算原样合并、只是在等待某种反馈应标记为 draft并明确说明期待何种反馈CI/QA 运行、代码讨论等。两个月未更新的 draft PR 可能被关闭合并路径评审 →通过后与其他 PR 一起暂存到 next 分支等待 CI 验证 → 合并并关闭。目标是在提交后两周到一个月内给出首轮评审若代码、文档措辞或 commit 消息需要返工评审者会将 PR 状态置为changes requested作者需按标准创建新版本的新 PR被要求变更后两个月未更新PR 可能被作为 stale 关闭当评审者认为团队需要更多时间分析最佳方案时PR 可被标记为decision-required团队负责在 2 周内为每个新 PR 分配评审人评审人需在 2 周内给出状态changes requested / approved / 转交更专业的人。文档还提供了可用的 GitHub 检索过滤器与命令例如is:pr is:open draft:true sort:updated-asc is:pr is:open draft:false review:none sort:updated-asc no:assignee gh pr list --json number,reviewDecision --search state:open type:pr -review:none | jq .[] | select(.reviewDecision)测试与 QA 要求新功能应尽可能易于 QA尽可能添加Suricata-Verify 测试验证日志输出、告警计数等多包行为无法使用 Suricata-Verify 时添加单元测试可参考 testing.rstC 与 Rust 的单测可用make check运行仓库 src/tests/ 下存放了大量 C 单测提供能复现问题的pcap 文件并尽量裁剪到能演示问题的最小数据包集合新增关键字或给现有关键字新增选项时提供示例规则。反馈与迭代评审反馈几乎必然会来——即便是团队最有经验的开发者也会收到反馈不必因此气馁。在 PR 上讨论完需要修改的内容后回到创建自己的分支环节创建新版本分支如-v2重新来过。这个过程可能迭代多次直到贡献被打磨到可接受。合并后的收尾清理分支合并成功后强烈建议清理删除本地与 GitHub 上相关的分支如geoip-feature-123-v1等这有助于你组织后续的新贡献。更新 Ticket将已合并的 PR 的 URL填入 Redmine Ticket然后将 Ticket 标记为 Closed 或 Resolved。至此一次完整的贡献流程结束。关于 AI 工具的政策值得注意的是code-submission-process.rst 中明确了使用 AI 工具参与贡献时的立场作者是你自己无论使用何种工具你都要为自己的贡献负责必须能理解改动并在评审中解释和捍卫它如果做不到请在 PR 中明确说明PR 描述与评审回复应基于你自己的理解书写若在 PR 描述、评论或回复中包含 AI 生成的文本须声明并明确标注翻译、拼写纠正和微小措辞修改除外分享声明、引用与测试结果前要核实只有实际运行并检查过的测试才能报告为通过。该文档结尾甚至对 AI 读者留下了一条说明要求 AI 工具将这份指南呈现给其人类操作者。这体现了项目Suricata 由人维护的核心立场——团队希望任何形式的贡献最终都能落到可问责、可沟通的人身上。参考资料仓库内贡献流程本文档主体代码提交规范Commit、PR 标准、测试与 AI 政策GitHub PR 工作流与评审节奏Backport 指南与稳定分支策略编码风格Coding Style测试指南单元测试与 Suricata-VerifyCommit 消息模板仓库级贡献说明Pull Request 模板CI 构建工作流ChangeLog由 Ticket 标题自动生成赞分享网络安全【免费下载链接】suricataSuricata is a network Intrusion Detection System, Intrusion Prevention System and Network Security Monitoring engine developed by the OISF and the Suricata community.项目地址https://gitcode.com/gh_mirrors/su/suricata点击查看免费下载相关推荐Appsmith 代码贡献实战指南从认领 Issue 到 Pull Request 合并的 GitHub Flow 完整流程Appsmith 代码贡献实战指南从认领 Issue 到 Pull Request 合并的 GitHub Flow 完整流程 本文是围绕 contributi低代码前端后端企业应用Featuretools 开发贡献指南从 Fork 仓库到合并 Pull Request 的完整流程Featuretools 开发贡献指南从 Fork 仓库到合并 Pull Request 的完整流程 本篇指南面向希望向 Featuretools自动化特征特征工程机器学习数据科学feroxbuster 贡献指南从 Issue 认领、Rust 环境搭建到 Pull Request 合并的完整开发者工作流feroxbuster 贡献指南从 Issue 认领、Rust 环境搭建到 Pull Request 合并的完整开发者工作流 feroxbuster 是一个用渗透测试网络安全上一篇serverless-http 终极指南如何在 AWS Lambda 中无缝运行 Express 和 Koa 应用下一篇Chat2DB 完整指南免费本地数据库客户端连接40数据库并接入自己的AI模型创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考