CyberStrikeAI 贡献规范实战指南：从 API、配置到高风险工具的分级 Checklist

CyberStrikeAI 贡献规范实战指南从 API、配置到高风险工具的分级 Checklist【免费下载链接】CyberStrikeAIThe system of action for AI-native cybersecurity—where intent becomes governed execution, evidence becomes operational memory, and every operation improves the next.项目地址: https://gitcode.com/GitHub_Trending/cy/CyberStrikeAI本文是 CyberStrikeAI 开源仓库的贡献指南深度解析围绕 docs/en-US/contributing-guide.md与 docs/zh-CN/contributing-guide.md 内容一致展开。你将掌握为这个AI 原生网络安全自动化平台新增功能、API、工具、前端页面与数据库字段时必须满足的全部工程门槛——从参数校验、审计写入、HITL人机协同策略到双语文档同步与自动化文档检查并能在源码层面定位每条规范的落地点写出可直接被评审通过的 PR。总原则七条基线期望贡献规范开篇即定义了一条核心纪律所有新增能力都必须同时交付功能 配套工程资产。以下是原文的七条总原则逐条对应到仓库中的落地位置新功能要有文档入口—— 每个重要功能必须在 docs/en-US/ 与 docs/zh-CN/ 两个导航体系中可被找到详见下文文档要求。新 API 要更新 OpenAPI—— 平台自带 OpenAPI 规范生成器接口变更必须同步。新前端文案要补中英文 i18n—— 所有可见文本进入 web/static/i18n/en-US.json 与 web/static/i18n/zh-CN.json。新配置要说明是否支持热应用—— 例如internal/config/tools_reload_test.go覆盖的工具热加载行为必须在文档中写清楚。新高风险工具要说明 HITL 策略—— 高风险操作必须明确是否需要人机协同审批。新数据库字段要兼容旧库—— 迁移必须幂等且可升级旧数据。新长任务要有状态、取消或恢复策略—— 可参考 internal/database/batch_task.go 与 internal/handler/task_manager.go 的任务状态机设计。这七条原则是后续所有 Checklist 的宪法每一条都对应着仓库中一个具体的机制而不是抽象口号。新增 API Checklist从 Handler 到 OpenAPI 的全链路要求新增或修改 HTTP 接口时逐项核对该清单Handler 参数校验明确入口处必须对请求参数做显式校验禁止把校验责任下放到业务深处。错误响应包含稳定error和可读message错误结构必须稳定客户端才能可靠解析。接口受认证保护除非明确是平台回调平台默认使用 Bearer JWT 认证见 internal/handler/openapi.go 中bearerAuth安全方案的声明。修改类接口写审计审计服务位于 internal/audit/handler 层大量调用审计记录如 internal/handler/auth.go、internal/handler/c2.go 等。长任务写监控或任务状态可复用internal/database/monitor.go与internal/database/batch_task.go的既有机制。更新internal/handler/openapi.go平台的 OpenAPI 3.0 规范由该文件动态生成见 GetOpenAPISpec它会根据请求的Host与 TLS 状态动态拼接servers.url因此新增接口后必须在此文件同步注册 schema 与路由。更新 API 文档或 Recipe即 docs/en-US/api-reference.md 与 docs/en-US/api-recipes.md。增加 Handler 测试仓库为每个 handler 配套了*_test.go例如 internal/handler/rbac_test.go、internal/handler/c2_tools_test.go新增接口必须同样补齐。新增配置 Checklist结构体、示例、默认值与热应用CyberStrikeAI 的配置体系以 Go 结构体为核心所有配置项必须满足config.Config结构体有字段配置根结构体定义在 internal/config/config.go包含Server、AI、MCP、Hitl、Security、Database、Auth、Audit、C2、Robots、MultiAgent、Project、Vision等区块每个字段都带yaml/jsontag。新增配置第一步就是在该结构体或对应子结构体中声明字段。config.yaml示例有注释示例文件 config.example.yaml 是全注释风格的权威参考例如server.port注释服务端口未启用 TLS 时为 http://localhost:8080audit.retention_days注释0 表示不自动清理。新增配置必须同步补注释。省略字段时有安全默认值源码中大量使用 0时回退默认值的模式例如 ProjectConfig.FactIndexMaxRunesEffective 在未配置时回退到 3500。默认值应偏向安全与保守。旧配置能启动向后兼容是硬性要求新增字段不能破坏已有配置文件解析。说明是否热应用部分能力支持运行时热加载见 internal/config/tools_reload_test.go 对工具配置重载的验证文档必须写明该配置生效时机是重启生效还是热应用。Web 设置页不会误删未知字段配置支持 Web 可视化编辑保存时必须保留未识别的字段防止把新版本才有的配置项覆盖掉。如影响高风险能力更新安全文档涉及 docs/en-US/security-model.md 或 docs/en-US/security-hardening.md 的能力必须同步说明风险。新增工具 ChecklistYAML 工具与 Go MCP 工具的统一规范工具是 CyberStrikeAI 的核心能力载体分为YAML 工具如 tools/nmap.yaml 这类声明式定义与Go 内置 MCP 工具位于 internal/mcp/两类规范要求一致工具名稳定、具体、避免重名例如nmap、sqlmap、hydra命名必须可预测。short_description能被tool_search搜到工具搜索依赖描述文本做语义检索short_description必须包含可检索的关键语义。以 tools/nmap.yaml 为例网络扫描端口/服务/脚本可选时序、自定义 NSE、OS 检测需 root。输入 schema 明确不用裸cmd包所有行为这是最关键的一条——每个工具必须声明结构化参数而非把一切塞进一个原始命令字符串。参考 nmap.yaml 的参数定义target必填、positional、ports-pflag、timingtemplate 生成-T{value}、nse_scripts--scriptflag、os_detectionbool flag-O、aggressivebool flag-A、scan_type、additional_args。每个参数声明了type、required、formatpositional / flag / template与defaultLLM 才能据此正确生成调用。输出可读且结构稳定工具输出应便于模型与用户理解并保持结构稳定。超时和错误路径可控参考 internal/mcp/execution_service.go 与 internal/mcp/tool_result_guard.go 的执行控制与结果保护机制。高风险操作不进全局白名单例如 nmap 的-O/-A需要 root默认falseSYN 扫描-sS同样标注需 root。全局白名单内的能力必须是最低风险子集。文档说明使用场景和风险工具文档需同时交代适用场景与风险边界如 nmap.yaml 中请确保有权限扫描目标。完整的工具声明式定义可参考 tools/ 目录下的 90 个 YAML 文件以及 internal/mcp/builtin 的内置 Go 工具。新增前端页面 Checklist复用模式与三态完备前端页面web/ 目录的六项硬性要求复用现有apiFetch、modal、通知和状态模式不要自创请求与弹窗模式保持交互一致性。所有可见文案补zh-CN.json和en-US.json双语文案文件各约 4000 行键按模块组织见 en-US.json 的common区块支持{{n}}形式的插值如minutesAgo: {{n}} min ago。详细规范见 docs/en-US/frontend-i18n.md。有 loading、empty、error 状态三态齐全是可用性底线。删除/高风险操作有确认破坏性操作必须二次确认。长文本和英文按钮不溢出考虑英文文案长度对布局的影响。浏览器控制台无错误提交前必须清理控制台告警。数据库变更 Checklist幂等迁移与旧库兼容涉及 internal/database/ 的变更时迁移幂等同一迁移在任意状态下重复执行都不出错。旧库可升级迁移必须覆盖旧版本数据库这一升级路径。字段默认值合理新增列必须有安全默认值避免破坏存量行。大表索引谨慎新增索引是刻意的性能决策不是顺手为之。测试空库和旧库空库初始化与旧库升级两条路径都要有测试覆盖参考 internal/database/ 下的*_test.go如 conversation_cleanup_test.go。发布说明提醒备份发布流程docs/en-US/release-process.md中必须提示升级前备份。高风险能力 Checklist七个必须回答的问题这是整个规范中最具 CyberStrikeAI 特色的一节。高风险能力包括Shell、WebShell、C2、外部 MCP 写入/执行、凭证访问、批量扫描。任何涉及这些能力的改动必须逐一回答谁能调用—— 对应 RBAC 边界见 docs/en-US/rbac.md 与 internal/handler/rbac.go。是否需要 HITL—— 人机协同审批策略机制实现见 internal/handler/hitl_execution.go最佳实践见 docs/en-US/hitl-best-practices.md。审计记录什么—— 审计系统internal/audit/service.go需记录谁在何时执行了什么高风险操作。如何取消—— 长任务/工具执行必须具备取消通道如 internal/handler/task_manager.go 的任务取消机制与 internal/c2/ 的会话管理。如何清理—— 临时文件、会话、beacon 等必须有清理路径参考 internal/attackchain/truncate.go 等清理实现。如何禁用—— 每个高风险能力都要有关闭开关例如config.example.yaml中 C2 相关配置的开关语义。默认是否关闭—— 默认关闭是安全默认值原则的具体化。这七个问题的答案必须形成文档而不是停留在代码注释里。文档要求双语文档、导航同步与自动化检查每个重要功能至少写六要素用途purpose配置config操作流程workflow风险边界risk boundary排错troubleshooting源码锚点source anchors中英文文件名必须一致文档按语言分目录存放文件名完全对齐docs/zh-CN/ docs/en-US/例如本文对应的规范文件即为docs/zh-CN/contributing-guide.md与docs/en-US/contributing-guide.md。同步三个导航入口每次文档变更必须更新docs/README.mddocs/zh-CN/README.mddocs/en-US/README.md三个导航文件按用户旅程组织部署 → 配置 → 排错开发 → 测试 → 贡献且文档约定明确Commands assume the repository root unless stated otherwise示例中的凭证与目标系统必须使用占位符。提交前运行文档检查脚本python3 scripts/check-docs.py该检查器会验证本地链接有效性fenced 代码块闭合中英文文件名对齐bilingual filename parity语言导航索引覆盖率locale index coverage根 README 中记录的 Go 版本与 go.mod 一致当前go 1.25.0。版本化示例应尽量从权威文件派生文档中出现的版本号、配置片段应引用 go.mod、config.example.yaml 等权威来源避免手工同步导致漂移。这与 docs/README.md 中文档与源码不一致即 documentation drift应上报的约定一脉相承。当文档、go.mod或检查器本身变更时GitHub Actions 的Documentation工作流会自动运行同一条命令即文档检查是 CI 门禁而非人工自觉。Review 关注点评审时优先看什么代码评审的优先级排序这是规范的收尾部分也决定了你提交 PR 前应自查的顺序行为回归behavior regressions—— 新改动是否破坏了既有行为安全边界security boundaries—— RBAC、HITL、白名单是否被绕过旧数据兼容old data compatibility—— 配置与数据库是否还能被旧实例读取错误处理error handling—— 错误路径是否可控、可读测试缺口test gaps—— 新增代码是否配套测试文档和 OpenAPI 是否同步docs and OpenAPI sync—— 文档、接口规范、i18n、导航是否保持一致。配套阅读与上手路径贡献规范不是孤立的它与仓库的开发者文档构成完整闭环docs/en-US/developer-guide.md —— 开发环境搭建与代码结构总览docs/en-US/testing.md —— 测试约定本仓库 handler、config、database、multiagent 均有大量测试佐证docs/en-US/tool-execution-governance.md —— 工具执行治理的完整模型docs/en-US/hitl-best-practices.md —— 高风险能力的人机协同细则docs/en-US/frontend-i18n.md —— 前端国际化的具体操作tools/README.md —— 工具 YAML 定义的编写参考。总结CyberStrikeAI 的贡献规范本质上是一套按风险分级的工程门禁——普通功能要求文档与 i18n 同步API 要求 OpenAPI 与审计同步而高风险能力则被要求回答谁能调用、是否需要 HITL、如何取消、如何禁用等七个安全问题。提交 PR 前把本文的每个 Checklist 逐项过一遍即可保证改动既满足 CI 门禁文档检查、测试也经得起安全与兼容性评审。【免费下载链接】CyberStrikeAIThe system of action for AI-native cybersecurity—where intent becomes governed execution, evidence becomes operational memory, and every operation improves the next.项目地址: https://gitcode.com/GitHub_Trending/cy/CyberStrikeAI创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考