Hack23/game

# 游戏模板 一个简洁、极简的模板，用于使用 React、TypeScript、Three.js 和 Vite 构建游戏 - 基于**安全优先原则**构建。 ## 徽章 [](https://github.com/Hack23/game/raw/master/LICENSE.md) [](https://scorecard.dev/viewer/?uri=github.com/Hack23/game) [](https://deepwiki.com/Hack23/game) ## 🔒 安全特性 此模板实施了与 **[Hack23 AB 的信息安全管理体系 (ISMS)](https://github.com/Hack23/ISMS-PUBLIC)** 保持一致的全面安全措施： ### 🛡️ 供应链安全 - **🛡️ OSSF Scorecard** - 自动化的供应链安全评估（[开源政策](https://github.com/Hack23/ISMS-PUBLIC/blob/main/Open_Source_Policy.md)） - **🔍 静态分析** - 针对漏洞的 CodeQL 扫描（[安全开发政策](https://github.com/Hack23/ISMS-PUBLIC/blob/main/Secure_Development_Policy.md)） - **📦 依赖保护** - 自动化的依赖漏洞检查（[开源政策](https://github.com/Hack23/ISMS-PUBLIC/blob/main/Open_Source_Policy.md)） - **📜 许可证合规性** - 自动检查依赖许可证（MIT, Apache-2.0, BSD variants, ISC, CC0-1.0, Unlicense）（[开源政策](https://github.com/Hack23/ISMS-PUBLIC/blob/main/Open_Source_Policy.md)） - **📋 SBOM 质量验证** - 使用 SBOMQS 进行自动化的 SBOM 质量评分，阈值为最低 7.0/10（[安全开发政策](https://github.com/Hack23/ISMS-PUBLIC/blob/main/Secure_Development_Policy.md)） - **🔐 Runner 加固** - 所有 CI/CD Runner 均通过审计日志进行加固（[安全开发政策](https://github.com/Hack23/ISMS-PUBLIC/blob/main/Secure_Development_Policy.md)） - **📋 安全策略** - GitHub 安全建议和漏洞报告（[信息安全政策](https://github.com/Hack23/ISMS-PUBLIC/blob/main/Information_Security_Policy.md)） - **🏷️ 固定依赖** - 所有 GitHub Actions 均固定到特定的 SHA 哈希值（[安全开发政策](https://github.com/Hack23/ISMS-PUBLIC/blob/main/Secure_Development_Policy.md)） ### 🔏 构建完整性与认证 - **📄 SBOM 生成** - 用于提高透明度的软件物料清单（[开源政策](https://github.com/Hack23/ISMS-PUBLIC/blob/main/Open_Source_Policy.md)） - **🔏 构建认证** - 构建完整性的加密证明（[安全开发政策](https://github.com/Hack23/ISMS-PUBLIC/blob/main/Secure_Development_Policy.md)） - **🛡️ 不可变发布** - 产物防篡改（[数据分类政策](https://github.com/Hack23/ISMS-PUBLIC/blob/main/Data_Classification_Policy.md)） - **🔐 构建完整性** - 原始构建保持不变 - **📋 审计追踪** - 完整的发布历史记录 - **🏆 产物验证** - 符合 SLSA 的构建来源 ### 🧪 安全测试 - **🕷️ ZAP 安全扫描** - OWASP ZAP 动态应用程序安全测试（[安全开发政策](https://github.com/Hack23/ISMS-PUBLIC/blob/main/Secure_Development_Policy.md)） - **⚡ Lighthouse 性能** - 自动化的性能和可访问性审计（[安全开发政策](https://github.com/Hack23/ISMS-PUBLIC/blob/main/Secure_Development_Policy.md)） ### 📚 安全文档 有关完整的安全策略映射和详细的合规性信息，请参阅： - 📊 **[ISMS 策略映射](docs/ISMS_POLICY_MAPPING.md)** - 全面的特性到策略映射 - 🔒 **[SECURITY.md](SECURITY.md)** - 安全策略和漏洞报告 - 🔐 **[ISMS-PUBLIC 仓库](https://github.com/Hack23/ISMS-PUBLIC)** - 完整的 ISMS 文档 ## 功能特性 - ⚡ **Vite** - 快速的构建工具和开发服务器 - ⚛️ **React 19** - 支持 hooks 的现代 React - 🔷 **TypeScript 6** - 目标为 ES2025 的严格类型检查 - 🧪 **Vitest** - 支持覆盖率的快速单元测试 - 🌲 **Cypress** - 可靠的 E2E 测试 - 📦 **ESLint** - 带有 TypeScript 规则的代码检查 - 🔄 **GitHub Actions** - 自动化测试和报告 - 🎮 **Three.js** - 高性能的 3D WebGL 渲染器 - 🎨 **@react-three/fiber** - Three.js 的 React 渲染器 - 🛠️ **@react-three/drei** - react-three-fiber 的实用辅助工具 - 🎵 **Howler.js** - 游戏音频库 - 📖 **TypeDoc** - 带有 ISMS 引用的 API 文档生成 ## 🤖 GitHub Copilot 自定义代理与技能 本仓库利用 GitHub Copilot 的最新功能进行 AI 辅助开发： ### 🎯 自定义代理 针对不同开发任务的专业 AI 专家： - **🎯 [product-task-agent](.github/agents/product-task-agent.md)** - 产品分析、质量改进和 GitHub Issue 创建 - **🎮 [game-developer](.github/agents/game-developer.md)** - 使用 @react-three/fiber 和 @react-three/drei 进行 Three.js 游戏开发 - **🎨 [frontend-specialist](.github/agents/frontend-specialist.md)** - React 19 和 TypeScript UI 开发 - **🧪 [test-engineer](.github/agents/test-engineer.md)** - 使用 Vitest 和 Cypress 进行全面测试 - **🔒 [security-specialist](.github/agents/security-specialist.md)** - 安全、合规性和供应链保护 - **📝 [documentation-writer](.github/agents/documentation-writer.md)** - 技术文档和指南 **了解更多：** [自定义代理文档](.github/agents/README.md) ### 🎓 代理技能 代理自动应用的可重用模式和最佳实践： - **🔒 [security-by-design](.github/skills/security-by-design/SKILL.md)** - 高级安全原则和执行规则 - **📋 [isms-compliance](.github/skills/isms-compliance/SKILL.md)** - ISMS 策略一致性验证 - **🎮 [react-threejs-game](.github/skills/react-threejs-game/SKILL.md)** - Three.js 游戏开发模式 - **🧪 [testing-strategy](.github/skills/testing-strategy/SKILL.md)** - 全面的测试模式 - **📝 [documentation-standards](.github/skills/documentation-standards/SKILL.md)** - 清晰的技术文档 - **⚡ [performance-optimization](.github/skills/performance-optimization/SKILL.md)** - React 和 Three.js 优化 **了解更多：** [代理技能指南](.github/skills/README.md) | [全面的 Copilot 指南](.github/COPILOT_GUIDE.md) ## 🚀 使用此模板 当您使用此模板创建新仓库时，请按照以下基本设置步骤操作，以确保所有安全和自动化功能正常工作： ### 1. 📋 设置仓库标签 标签对于自动化的 Pull Request 分类和发布说明生成至关重要。 **运行设置工作流：** 1. 转到 **Actions** → **Setup Repository Labels** 2. 点击 **"Run workflow"** 3. 选择是否重新创建所有标签（可选） 4. 等待完成 这将创建所有必要的标签，用于： - 🚀 功能和增强 - 🐛 Bug 修复 - 🎮 游戏开发（图形、音频、游戏逻辑） - 🔒 安全和合规性 - 📦 依赖和基础设施 ### 2. 🌐 启用 GitHub Pages 部署 启用 GitHub Pages 以在创建发布时自动部署您的游戏。 **设置 GitHub Pages：** 1. 转到 **Settings** → **Pages** 2. 在 **Source** 下，选择 **"GitHub Actions"** 3. 保存配置 当您运行发布工作流时，您的游戏将自动部署到 `https://your-username.github.io/your-repo-name/`。 ### 3. 🔒 更新安全徽章 更新 OpenSSF Scorecard 徽章以指向您的仓库。 **编辑 README：** ``` [](https://scorecard.dev/viewer/?uri=github.com/your-username/your-repo-name) ``` 将 `your-username/your-repo-name` 替换为您实际的 GitHub 仓库路径。 ### 4. 🎮 开始构建您的游戏 配置好模板后，您现在可以： 1. **在本地或 Codespaces 中开发** npm install npm run dev 2. **创建 Pull Request** - 标签将被自动应用 3. **运行测试** - 每次 push/PR 时自动测试 4. **创建发布** - 使用发布工作流进行部署 5. **监控安全** - 自动化的安全扫描和评分 ### 🔄 可用工作流 您的仓库包含以下自动化工作流： | 工作流 | 触发器 | 目的 | | -------------------------------- | ---------------- | ----------------------------------------------------------------------------------------------- | | **Setup Repository Labels** | 手动 | 创建用于 PR 分类的所有必需标签 | | **Setup Copilot Environment** | 手动 | 验证并记录 Copilot MCP 服务器配置 | | **Test and Report** | Push/PR | 运行单元测试、E2E 测试、许可证合规性检查、SBOM 质量验证，并生成覆盖率报告 | | **Build, Attest and Release** | 手动/标签 | 创建带有 SBOM、许可证验证和认证的安全发布 | | **CodeQL Analysis** | Push/PR/计划任务 | 针对安全漏洞的静态代码分析 | | **Dependency Review** | PR | 检查依赖项中的已知漏洞 | | **Scorecard Analysis** | Push/计划任务 | OSSF 供应链安全评估 | | **ZAP Security Scan** | 手动 | 对已部署的应用程序进行动态安全测试 | | **Lighthouse Performance** | 手动 | 性能和可访问性审计 | ### 🛡️ 安全特性开箱即用 配置完成后，您的仓库将自动提供与 **[Hack23 AB 的 ISMS](https://github.com/Hack23/ISMS-PUBLIC)** 保持一致的全面安全保护： - **🛡️ OSSF Scorecard** - 自动化的供应链安全评估（[开源政策](https://github.com/Hack23/ISMS-PUBLIC/blob/main/Open_Source_Policy.md)） - **🔍 静态分析** - 针对漏洞的 CodeQL 扫描（[安全开发政策](https://github.com/Hack23/ISMS-PUBLIC/blob/main/Secure_Development_Policy.md)） - **📦 依赖保护** - 自动化的依赖漏洞检查（[开源政策](https://github.com/Hack23/ISMS-PUBLIC/blob/main/Open_Source_Policy.md)） - **📜 许可证合规性** - 自动检查依赖许可证（[开源政策](https://github.com/Hack23/ISMS-PUBLIC/blob/main/Open_Source_Policy.md)） - **📋 SBOM 质量验证** - 自动化的 SBOM 质量评分（[安全开发政策](https://github.com/Hack23/ISMS-PUBLIC/blob/main/Secure_Development_Policy.md)） - **🔐 Runner 加固** - 所有 CI/CD Runner 均已加固（[安全开发政策](https://github.com/Hack23/ISMS-PUBLIC/blob/main/Secure_Development_Policy.md)） - **📋 安全策略** - GitHub 安全建议和漏洞报告（[信息安全政策](https://github.com/Hack23/ISMS-PUBLIC/blob/main/Information_Security_Policy.md)） - **🏷️ 固定依赖** - 所有 GitHub Actions 均固定到特定的 SHA 哈希值（[安全开发政策](https://github.com/Hack23/ISMS-PUBLIC/blob/main/Secure_Development_Policy.md)） - **📄 SBOM 生成** - 用于提高透明度的软件物料清单（[开源政策](https://github.com/Hack23/ISMS-PUBLIC/blob/main/Open_Source_Policy.md)） - **🔏 构建认证** - 构建完整性的加密证明（[安全开发政策](https://github.com/Hack23/ISMS-PUBLIC/blob/main/Secure_Development_Policy.md)） - **🛡️ 不可变发布** - 产物防篡改（[数据分类政策](https://github.com/Hack23/ISMS-PUBLIC/blob/main/Data_Classification_Policy.md)） - **🔐 构建完整性** - 原始构建保持不变 - **📋 审计追踪** - 完整的发布历史记录 - **🏆 产物验证** - 符合 SLSA 的构建来源 - **🕷️ ZAP 安全扫描** - OWASP ZAP 动态应用程序安全测试（[安全开发政策](https://github.com/Hack23/ISMS-PUBLIC/blob/main/Secure_Development_Policy.md)） - **⚡ Lighthouse 性能** - 自动化的性能和可访问性审计（[安全开发政策](https://github.com/Hack23/ISMS-PUBLIC/blob/main/Secure_Development_Policy.md)） 有关完整的特性到策略映射，请参阅 **[ISMS 策略映射](docs/ISMS_POLICY_MAPPING.md)**。 ### 🎯 后续步骤 1. 将 `src/components/` 中的示例游戏**替换**为您的游戏逻辑 2. 将游戏资产**添加**到 `public/assets/` 目录 3. **创建您的第一个 PR** 以查看自动标记的实际效果 4. **运行您的第一次发布** 以部署到 GitHub Pages 5. 通过自动生成的安全报告**监控安全性** 所有安全工作流将保护您的游戏免受漏洞侵害，同时通过认证和 SBOM 生成提供完全的透明度。 ## 开发环境 此模板包含一个完全配置好的开发环境： - **🚀 GitHub Codespaces** - 零配置的开发环境 - **🤖 GitHub Copilot** - 带有代码建议的 AI 辅助开发 - **💬 Copilot Chat** - 用于调试和解释的编辑器内 AI 助手 - **🔧 VS Code 扩展** - 为游戏开发预配置的扩展 - **🔒 安全容器** - 带有安全特性的加固开发容器 - **🔌 MCP 服务器** - 用于增强 Copilot 功能的模型上下文协议服务器 ### 🚀 Codespaces 设置 此仓库已完全配置好 GitHub Codespaces，提供： - **一键设置** - 无需配置即可立即开始编码 - **预安装依赖** - 所有工具和库均可直接使用 - **已配置的测试环境** - Cypress 和 Vitest 可直接运行 - **GitHub Copilot 集成** - 带有 MCP 服务器的 AI 驱动代码辅助- **优化的性能** - 为游戏开发配置的容器 ### 🔌 用于增强 Copilot 的 MCP 服务器 此仓库配置了模型上下文协议 (MCP) 服务器，可增强 GitHub Copilot 的功能： - **🗂️ Filesystem Server** - 用于代码导航和编辑的安全文件访问 - **🐙 GitHub Server** - 仓库上下文、Issue 和 PR 集成 - **📚 Git Server** - 版本控制历史和代码演进理解 - **🧠 Memory Server** - 在 Copilot 对话中维护上下文 - **🔍 Brave Search Server** - 文档搜索（可选，需要 API 密钥） - **🎭 Playwright Server** - 用于测试和调试的浏览器自动化 **配置文件：** - `.github/copilot-instructions.md` - Copilot 的编码指南 - `docs/MCP_CONFIGURATION.md` - 详细的 MCP 设置文档 **注意：** MCP 服务器在 GitHub Codespaces 环境中会自动配置，不需要单独的配置文件。 **了解更多：** 有关详细的设置和使用说明，请参阅 [MCP 配置指南](docs/MCP_CONFIGURATION.md)。 ### 🔑 配置 GitHub 个人访问令牌 **product-task-agent** 和 **GitHub MCP server** 需要个人访问令牌 (PAT) 才能创建和管理 Issue、访问仓库数据以及执行其他 GitHub 操作。 #### 创建个人访问令牌 1. **生成细粒度令牌**（推荐） - 转到 **GitHub Settings** → **Developer settings** → **Personal access tokens** → **Fine-grained tokens** - 点击 **"Generate new token"** - 填写详细信息： - **Token name**：`copilot-mcp-game`（或您偏好的名称） - **Expiration**：选择适当的有效期（例如，90 天） - **Repository access**：选择 **"Only select repositories"** → 选择您的游戏仓库 - **Repository permissions**（必需）： - **Issues**：Read and write（用于创建和管理 Issue） - **Contents**：Read-only（用于代码分析） - **Metadata**：Read-only（自动包含） - **Pull requests**：Read and write（可选，用于 PR 管理） - **Workflows**：Read-only（可选，用于工作流状态） - 点击 **"Generate token"** 并**立即复制令牌**（您以后将无法再看到它） 2. **替代方案：经典令牌** - 转到 **GitHub Settings** → **Developer settings** → **Personal access tokens** → **Tokens (classic)** - 点击 **"Generate new token"** → **"Generate new token (classic)"** - 选择范围： - ✅ `repo`（私有仓库的完全控制） - **必需** - ✅ `read:org`（读取组织成员身份） - 可选 - ✅ `workflow`（更新 GitHub Actions 工作流） - 可选 - 点击 **"Generate token"** 并**复制令牌** #### 在您的环境中设置令牌 **对于 GitHub Codespaces：** 1. 在 GitHub 上转到您的仓库 2. 点击 **Settings** → **Secrets and variables** → **Codespaces** 3. 点击 **"New repository secret"** 4. 名称：`GITHUB_TOKEN` 5. 值：粘贴您的个人访问令牌 6. 点击 **"Add secret"** 该令牌将在您的 Codespace 环境中自动可用。 **对于本地开发：** ``` # Linux/macOS - 添加到 ~/.bashrc 或 ~/.zshrc export GITHUB_TOKEN="your_token_here" # Windows PowerShell - 添加到你的 PowerShell 配置文件 $env:GITHUB_TOKEN="your_token_here" # Windows Command Prompt set GITHUB_TOKEN=your_token_here ``` **验证令牌是否已设置：** ``` # 在你的终端中 echo $GITHUB_TOKEN # Linux/macOS echo %GITHUB_TOKEN% # Windows CMD echo $env:GITHUB_TOKEN # Windows PowerShell ``` #### 所需权限摘要 | 权限 | 访问级别 | 目的 | |------------|--------------|---------| | **Issues** | Read and write | 通过 product-task-agent 创建和管理 GitHub Issue | | **Contents** | Read-only | 分析代码和仓库结构 | | **Metadata** | Read-only | 访问仓库元数据（自动） | | **Pull requests** | Read and write | 管理 PR（可选） | | **Workflows** | Read-only | 检查工作流状态（可选） | #### 安全最佳实践 - ✅ **使用细粒度令牌**并具有最低限度的所需权限 - ✅ **设置适当的有效期**（推荐 90 天） - ✅ **限制为特定仓库**而不是所有仓库 - ✅ **绝不将令牌提交**到源代码中 - ✅ **使用仓库密钥**用于 Codespaces - ✅ **在过期前定期轮换令牌** - ✅ **在 GitHub 设置中撤销未使用的令牌** #### 故障排除 **令牌无效：** - 验证令牌是否具有所需权限 - 检查令牌是否已过期 - 确保 `GITHUB_TOKEN` 环境变量设置正确 - 设置令牌后重启您的 Codespace 或终端 **创建 Issue 时出现权限错误：** - 确保令牌具有 **Issues: Read and write** 权限 - 验证仓库访问权限是否包含您的目标仓库 - 检查令牌是否已被撤销 ``` graph LR A[Developer] -->|Opens in Codespace| B[Container Setup] B -->|Auto-configures| C[Development Environment] C -->|Provides| D[VS Code + Extensions] C -->|Initializes| E[Node.js Environment] C -->|Configures| F[Testing Tools] D -->|Includes| G[GitHub Copilot] D -->|Includes| H[ESLint Integration] D -->|Includes| I[Debug Tools] E -->|Installs| J[Three.js] E -->|Installs| K[React 19] E -->|Installs| L[TypeScript] F -->|Prepares| M[Cypress E2E] F -->|Prepares| N[Vitest Unit Tests] G -->|Assists with| O[Game Logic] G -->|Suggests| P[Game Components] classDef primary fill:#e3f2fd,stroke:#1565c0,stroke-width:2px,color:#000 classDef tools fill:#e8f5e8,stroke:#2e7d32,stroke-width:2px,color:#000 classDef ai fill:#fff3e0,stroke:#e65100,stroke-width:2px,color:#000 classDef testing fill:#f3e5f5,stroke:#4a148c,stroke-width:2px,color:#000 class A,B,C primary class D,E,F tools class G,O,P ai class M,N testing class J,K,L tools class H,I tools ``` ## 安全工作流 ``` graph TD A[🔒 Code Push/PR] --> B{🛡️ Security Gates} B --> |🔍 Code Analysis| C[CodeQL Scanning] B --> |📦 Dependencies| D[Dependency Review] B --> |📜 License Check| E[License Compliance] B --> |🏗️ Supply Chain| F[OSSF Scorecard] C --> |🚨 Vulnerabilities| G[Security Alerts] D --> |⚠️ Known CVEs| G E --> |� Invalid Licenses| G F --> |�📊 Security Score| H[Security Dashboard] G --> I[🚫 Block Merge] H --> J[✅ Security Badge] subgraph "🔐 Protection Layers" K[Runner Hardening] L[Pinned Actions] M[Audit Logging] end subgraph "🧪 Runtime Security Testing" N[🕷️ ZAP DAST Scan] O[⚡ Lighthouse Audit] P[🌐 Live Site Testing] end J --> N N --> |🔍 Dynamic Scan| O O --> |📊 Performance Report| P %% Styling classDef security fill:#ffebee,stroke:#c62828,stroke-width:2px,color:#000 classDef analysis fill:#e8f5e8,stroke:#2e7d32,stroke-width:2px,color:#000 classDef protection fill:#e3f2fd,stroke:#1565c0,stroke-width:2px,color:#000 classDef alert fill:#fff3e0,stroke:#ef6c00,stroke-width:2px,color:#000 classDef runtime fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px,color:#000 class A,B,I security class C,D,E,F analysis class K,L,M protection class G,H,J alert class N,O,P runtime ``` ## 测试与报告工作流 ``` graph TD A[🚀 Code Push/PR] --> B{🔍 Prepare Environment} B --> |✅ Dependencies| C[🏗️ Build Validation] B --> |✅ Cypress Cache| D[🧪 Unit Tests] B --> |✅ Display Setup| E[🌐 E2E Tests] C --> |✅ Build Success| F{📊 Parallel Testing} F --> D F --> E D --> |📈 Coverage Report| G[📋 Test Reports] E --> |🎬 Videos & Screenshots| G G --> H[📤 Artifact Upload] H --> I[✨ Combined Reports] %% Styling classDef startEnd fill:#e1f5fe,stroke:#01579b,stroke-width:2px,color:#000 classDef process fill:#f3e5f5,stroke:#4a148c,stroke-width:2px,color:#000 classDef test fill:#e8f5e8,stroke:#1b5e20,stroke-width:2px,color:#000 classDef report fill:#fff3e0,stroke:#e65100,stroke-width:2px,color:#000 classDef artifact fill:#fce4ec,stroke:#880e4f,stroke-width:2px,color:#000 class A,I startEnd class B,C,F process class D,E test class G,H report class H artifact ``` ## 快速开始 ``` # 使用 GitHub Codespaces # 点击仓库上的 "Code" 按钮，然后选择 "Open with Codespaces" # 或者本地开发： # 安装依赖 npm install # 启动开发服务器 npm run dev # 为生产环境构建 npm run build # 运行单元测试 npm run test # 运行 E2E 测试 npm run test:e2e # 检查许可证合规性 npm run test:licenses # 生成 API 文档 npm run docs:api ``` ## Three.js 集成 此模板使用 Three.js 进行高性能的 3D 游戏渲染： - 基于 WebGL 的现代 3D 渲染 - 通过 @react-three/fiber 优化的性能 - 通过 @react-three/fiber 的 React 集成 - 通过 @react-three/drei 提供的实用辅助工具 - 通过 Howler.js 提供的声音支持 - 响应式 3D 画布 - 触摸和鼠标输入处理 - 带有 OrbitControls 的摄像机控制 示例游戏组件： ``` import { Canvas } from "@react-three/fiber"; import { OrbitControls } from "@react-three/drei"; export function Game() { return ( {/* Lighting */} {/* 3D Objects */} {/* Camera Controls */} ); } ``` ## 测试 ### 单元测试 - 在 jsdom 环境中使用 Vitest - 为 React Testing Library 配置 - 自动生成覆盖率报告 - 运行命令：`npm run test` ### E2E 测试 - 使用 Cypress 进行端到端测试 - 自动启动开发服务器 - 失败时生成截图和视频 - 运行命令：`npm run test:e2e` ### 许可证合规性 - 使用 `license-compliance` 自动检查依赖许可证 - 仅允许批准的开源许可证（MIT, Apache-2.0, BSD variants, ISC, CC0-1.0, Unlicense） - 防止具有限制性或未知许可证的依赖 - 运行命令：`npm run test:licenses` ### SBOM 质量验证 - 在 CI/CD 构建期间使用 [SBOMQS](https://github.com/interlynk-io/sbomqs) 进行自动化的 SBOM 质量评估 - 验证 SBOM 在多个标准（NTIA-minimum-elements, BSI v1.1/v2.0, Semantic, Quality, Sharing, Structural）下的完整性 - 强制要求最低质量分数为 **7.0/10**，以确保高质量的软件物料清单 - 检查基本组件：名称、版本、唯一 ID、供应商、许可证、校验和以及依赖关系 - 阻止 SBOM 质量不足的构建，以维护供应链透明度 - 提供包含可操作改进建议的详细质量报告 ### CI/CD 流水线 ``` flowchart LR subgraph "🔧 CI Pipeline" A1[📝 Code Changes] --> A2[🔍 Lint & Type Check] A2 --> A3[🏗️ Build] A3 --> A4[🧪 Test] A4 --> A5[📊 Report] end subgraph "🔒 Security Pipeline" S1[🛡️ CodeQL Analysis] S2[📦 Dependency Review] S3[🏆 OSSF Scorecard] S4[� SBOM Quality Check] S5[�🔐 Runner Hardening] end subgraph "📈 Test Coverage" B1[Unit Tests
80%+ Coverage] B2[E2E Tests
Critical Flows] B3[Type Safety
Strict Mode] end subgraph "🎯 Outputs" C1[📄 Coverage Reports] C2[🎬 Test Videos] C3[📸 Screenshots] C4[📋 JUnit XML] C5[🛡️ Security Reports] end A4 --> B1 A4 --> B2 A4 --> B3 A1 --> S1 A1 --> S2 A1 --> S3 A1 --> S4 A1 --> S5 A5 --> C1 A5 --> C2 A5 --> C3 A5 --> C4 S1 --> C5 S2 --> C5 S3 --> C5 S4 --> C5 %% Styling classDef pipeline fill:#e3f2fd,stroke:#1565c0,stroke-width:2px classDef security fill:#ffebee,stroke:#c62828,stroke-width:2px classDef testing fill:#e8f5e8,stroke:#2e7d32,stroke-width:2px classDef output fill:#fff8e1,stroke:#f57c00,stroke-width:2px class A1,A2,A3,A4,A5 pipeline class S1,S2,S3,S4 security class B1,B2,B3 testing class C1,C2,C3,C4,C5 output ``` ### 安全工作流 - **CodeQL Analysis**：在 push/PR 时自动进行漏洞扫描 - **Dependency Review**：检查依赖项中的已知漏洞 - **License Compliance**：验证所有依赖项均使用已批准的开源许可证 - **SBOM Quality Validation**：使用 SBOMQS 进行自动化的 SBOM 质量评估，最低要求分数为 7.0/10 - **OSSF Scorecard**：带有公开评分的供应链安全评估 - **Runner Hardening**：所有 CI/CD Runner 均使用加固的安全策略 ## 🚀 发布管理 此模板包含一个全面的安全优先发布工作流，具有自动化的版本控制、安全认证和部署功能。 ### 发布流程 ``` flowchart TD A[🚀 Release Trigger] --> B{📋 Release Type} B -->|🏷️ Tag Push| C[🔄 Automatic Release] B -->|⚡ Manual Dispatch| D[📝 Manual Release] C --> E[📦 Prepare Phase] D --> E E --> F[🏗️ Build & Test] F --> G[🔒 Security Validation] G --> H[📄 Generate SBOM] H --> I[🔏 Create Attestations] I --> J[📋 Draft Release Notes] J --> K[🌐 Deploy to Pages] K --> L[📢 Publish Release] subgraph "🔒 Security Layers" M[SLSA Build Provenance] N[SBOM Attestation] O[Artifact Signing] P[Supply Chain Verification] end I --> M I --> N I --> O G --> P %% Styling classDef trigger fill:#e1f5fe,stroke:#01579b,stroke-width:2px classDef process fill:#f3e5f5,stroke:#4a148c,stroke-width:2px classDef security fill:#ffebee,stroke:#c62828,stroke-width:2px classDef deploy fill:#e8f5e8,stroke:#1b5e20,stroke-width:2px class A,B,C,D trigger class E,F,J,K,L process class G,H,I,M,N,O,P security ``` ### 🏷️ 发布类型 #### 自动发布（基于标签） ``` # 创建并推送 tag 以触发自动发布 git tag v1.0.0 git push origin v1.0.0 ``` #### 手动发布（工作流调度） - 导航至 **Actions** → **Build, Attest and Release** - 点击 **Run workflow** - 指定版本（例如，`v1.0.1`）和预发布状态 - 工作流将自动处理版本升级和打标签 ### 📋 自动发布说明 发布说明使用语义化标签自动生成： ``` graph LR A[🔄 PR Labels] --> B[📝 Release Drafter] B --> C[📊 Categorized Notes] subgraph "🏷️ Label Categories" D[🚀 New Features] E[🎮 Game Development] F[🔒 Security & Compliance] G[🐛 Bug Fixes] H[📦 Dependencies] I[🧪 Test Coverage] end A --> D A --> E A --> F A --> G A --> H A --> I C --> J[📢 GitHub Release] classDef labels fill:#fff3e0,stroke:#e65100,stroke-width:2px classDef process fill:#e3f2fd,stroke:#1565c0,stroke-width:2px classDef output fill:#e8f5e8,stroke:#2e7d32,stroke-width:2px class D,E,F,G,H,I labels class A,B,C process class J output ``` #### 发布说明分类 - **🚀 新功能** - 主要功能添加 - **🎮 游戏开发** - 游戏逻辑、图形、音频改进 - **🎨 UI/UX 改进** - 界面和设计更新 - **🏗️ 基础设施与性能** - 构建和性能优化 - **🔄 代码质量与重构** - 代码改进和测试 - **🔒 安全与合规性** - 安全更新和修复 - **📝 文档** - 文档改进 - **📦 依赖项** - 依赖项更新 - **🐛 Bug 修复** - 错误修复和补丁 ### 🔒 安全认证与 SBOM #### 软件物料清单 (SBOM) 每次发布都包含一份 SPDX 格式的全面 SBOM： ``` { "SPDXID": "SPDXRef-DOCUMENT", "name": "game-v1.0.0", "packages": [ { "SPDXID": "SPDXRef-Package-react", "name": "react", "versionInfo": "19.1.0", "licenseConcluded": "MIT" } ] } ``` #### 构建来源认证 符合 SLSA 的构建认证提供加密证明： ``` { "_type": "https://in-toto.io/Statement/v0.1", "predicateType": "https://slsa.dev/provenance/v0.2", "subject": [ { "name": "game-v1.0.0.zip", "digest": { "sha256": "abc123..." } } ], "predicate": { "builder": { "id": "https://github.com/actions/runner" }, "buildType": "https://github.com/actions/workflow@v1" } } ``` #### 验证命令 ``` # 验证构建来源 gh attestation verify game-v1.0.0.zip \ --owner Hack23 --repo game # 验证 SBOM 证明 gh attestation verify game-v1.0.0.zip \ --owner Hack23 --repo game \ --predicate-type https://spdx.dev/Document ``` # 🔒 不可变发布 此仓库使用 **GitHub 的不可变发布** 来防止对已发布版本的未经授权修改。 ## 什么是不可变发布？ 不可变发布会在发布后锁定发布产物，确保： - **🛡️ 供应链安全** - 产物无法被篡改 - **🔐 构建完整性** - 原始构建保持不变 - **📋 审计追踪** - 完整的发布历史记录 ## 如何启用 ### 对于您的仓库： 1. 转到 **Settings** → **General** 2. 滚动到 **"Releases"** 部分 3. 勾选 **"Enable release immutability"** 4. ⚠️ 仅适用于**未来的发布** ### 对于您的组织： 1. 转到 **Organization Settings** → **Repository** → **General** 2. 在 **"Releases"** 部分，选择策略： - **All repositories** - 应用于所有组织仓库 - **Selected repositories** - 选择特定仓库 3. ⚠️ 仅适用于**未来的发布** ## 验证 ``` # 验证发布构件未被篡改 gh attestation verify game-v1.1.4.zip --owner Hack23 --repo game ``` _这是我们安全优先方法的一部分，同时还包括 OSSF Scorecard、SLSA 认证和自动化扫描。_ ### 📦 发布产物 每个版本都包含多个具有完全可追溯性的产物： ``` 📦 Release v1.0.0 ├── 🎮 game-v1.0.0.zip # Built application ├── 📄 game-v1.0.0.spdx.json # Software Bill of Materials ├── 🔏 game-v1.0.0.zip.intoto.jsonl # Build provenance attestation └── 📋 game-v1.0.0.spdx.json.intoto.jsonl # SBOM attestation ``` ### 🌐 部署流水线 ``` sequenceDiagram participant Dev as 👨‍💻 Developer participant GH as 🐙 GitHub participant CI as 🔄 CI/CD participant Sec as 🔒 Security participant Pages as 🌐 GitHub Pages Dev->>GH: 🏷️ Push Tag/Manual Trigger GH->>CI: 🚀 Start Release Workflow CI->>CI: 🧪 Run Tests & Build CI->>Sec: 🔍 Security Scans Sec-->>CI: ✅ Security Validated CI->>Sec: 📄 Generate SBOM CI->>Sec: 🔏 Create Attestations Sec-->>CI: 📋 Security Artifacts Ready CI->>GH: 📝 Draft Release Notes CI->>GH: 📦 Upload Artifacts CI->>Pages: 🌐 Deploy Application Pages-->>CI: ✅ Deployment Success CI->>GH: 📢 Publish Release GH-->>Dev: 🎉 Release Complete ``` ### 🔐 安全合规性 #### OSSF Scorecard 集成 - **自动评分**供应链安全实践 - **公开透明**并带有安全徽章 - **持续监控**安全态势 #### 供应链保护 - **固定依赖** - 所有 GitHub Actions 均固定到 SHA 哈希值 - **依赖扫描** - 自动漏洞检测 - **SLSA 合规性** - 构建完整性和来源 - **已签名的产物** - 发布的加密验证 ### 📊 发布指标 通过内置指标跟踪发布质量和安全性： - **🔒 安全评分** - OSSF Scorecard 评级 - **📈 测试覆盖率** - 单元和 E2E 测试覆盖率 - **🏷️ 漏洞数量** - 已知安全问题 - **📦 依赖健康状况** - 过时/有漏洞的依赖项 - **🚀 构建成功率** - CI/CD 流水线可靠性 ## 构建您的游戏 此模板为游戏开发提供了一个**安全的基础**： 1. 用您的游戏逻辑替换计数器示例 2. 在 `src/components/` 中添加游戏特定的组件 3. 创建游戏状态管理（Context API、Zustand 等） 4. 为游戏逻辑添加单元测试 5. 为游戏流程创建 E2E 测试 6. 使用自动化工作流**创建发布** 7. 通过 OSSF Scorecard 和认证**监控安全性** 8. 使用包含的**安全加固** GitHub Actions 进行部署 所有安全工作流将自动保护您的游戏免受常见漏洞和供应链攻击，同时通过 SBOM 和认证提供完全的透明度。 ## 📚 文档 ### 开发指南 - **[Copilot 快速入门指南](docs/COPILOT_QUICK_START.md)** - 在此仓库中开始使用 GitHub Copilot - **[MCP 配置指南](docs/MCP_CONFIGURATION.md)** - 模型上下文协议的设置和使用 - **[MCP 架构](docs/MCP_ARCHITECTURE.md)** - MCP 集成的视觉指南 - **[Copilot 说明](.github/copilot-instructions.md)** - AI 辅助的编码指南 ### 安全与合规性 - 🔒 **[SECURITY.md](SECURITY.md)** - 安全策略和漏洞报告 - 🛡️ **[SECURITY_HEADERS.md](SECURITY_HEADERS.md)** - 安全标头实现 - 📊 **[ISMS 策映射](docs/ISMS_POLICY_MAPPING.md)** - 完整的特性到策略映射 - 🔐 **[ISMS-PUBLIC 仓库](https://github.com/Hack23/ISMS-PUBLIC)** - Hack23 AB 的完整 ISMS ### ISMS 核心政策 - 🔐 **[信息安全政策](https://github.com/Hack23/ISMS-PUBLIC/blob/main/Information_Security_Policy.md)** - 整体安全治理 - 🛠️ **[安全开发政策](https://github.com/Hack23/ISMS-PUBLIC/blob/main/Secure_Development_Policy.md)** - SDLC 和 CI/CD 要求 - 📦 **[开源政策](https://github.com/Hack23/ISMS-PUBLIC/blob/main/Open_Source_Policy.md)** - 供应链安全 - 🏷️ **[数据分类政策](https://github.com/Hack23/ISMS-PUBLIC/blob/main/Data_Classification_Policy.md)** - 数据处理要求 - 🔒 **[隐私政策](https://github.com/Hack23/ISMS-PUBLIC/blob/main/Privacy_Policy.md)** - 隐私和 GDPR 合规性 - 🔑 **[访问控制政策](https://github.com/Hack23/ISMS-PUBLIC/blob/main/Access_Control_Policy.md)** - 身份验证和授权 祝您游戏愉快！🎮🔒

标签：3D游戏, CI/CD安全, CodeQL, DNS 反向解析, License合规, Llama, OSSF Scorecard, React, SBOM, Syscalls, Three.js, TypeScript, Vite, WebGL, XML 请求, 信息安全管理, 前端模板, 安全专业人员, 安全开发, 安全插件, 安全策略, 安全评估工具, 提示词设计, 最小化模板, 游戏开发, 硬件无关, 网络安全审计, 脚手架, 自动化攻击, 错误基检测, 静态代码分析