软件安全标准

Appearance

AI 助手 - 安全发布引导 ​

本页面专为 AI 助手设计

用户可以将本页面的 URL 发送给 AI 助手，AI 助手可以阅读本页内容，逐步引导用户完成软件安全发布的全部流程。

使用示例

将以下提示词发送给你的 AI 助手：

"使用 websearch 访问 https://security-platform-docs.vercel.app/ai/ 告诉我接下来该做什么"

AI 会阅读本页内容，根据你的进度逐步引导你完成安全发布流程。

面向 AI 助手的说明 ​

你正在阅读一份软件安全发布流程指南。请根据以下步骤，引导用户完成从创建 GitHub 账号到提交安全审核的全流程。每个步骤请逐一确认用户是否完成，再继续下一步。

流程总览 ​

第 1 步：创建 GitHub 账号
    ↓
第 2 步：申请加入 secure-artifacts 组织
    ↓
第 3 步：将项目上传到组织
    ↓
第 4 步：配置 GitHub Actions CI
    ↓
第 5 步：提交安全审核

第 1 步：创建 GitHub 账号 ​

如果用户已有 GitHub 账号，跳过此步骤。

  1. 访问 https://github.com/signup
  2. 按照页面提示填写用户名、邮箱和密码
  3. 完成邮箱验证
  4. 登录 GitHub

确认点： 请用户提供其 GitHub 用户名，确认账号已创建。

第 2 步：申请加入 secure-artifacts 组织 ​

所有需要安全审核的项目必须托管在 secure-artifacts GitHub 组织下。

2.1 提交加入组织申请 ​

  1. 打开安全管理平台的提交页面：https://security-platform-web.vercel.app
  2. 选择 "申请加入组织" 流程
  3. 填写以下信息：
    • GitHub 用户名或主页链接 - 例如 your-username 或 https://github.com/your-username
    • Teams 链接 - Microsoft Teams 联系链接
    • 提交者邮箱 - 工作邮箱
  4. 点击提交

2.2 接受组织邀请 ​

管理员审核通过后会发送 GitHub 组织邀请：

  1. 关注 GitHub 通知和 Teams 通知
  2. 收到邀请后，访问 https://github.com/orgs/secure-artifacts/invitation
  3. 点击 Join 按钮接受邀请

确认点： 请用户确认已收到并接受了组织邀请。

第 3 步：将项目上传到组织 ​

加入组织后，将项目添加到 secure-artifacts 组织下。

方式一：Fork 项目（推荐） ​

如果项目已经在用户个人的 GitHub 上：

  1. 打开项目页面
  2. 点击右上角 Fork 按钮
  3. 在 Owner 下拉菜单中选择 secure-artifacts
  4. 点击 Create fork

方式二：创建新项目 ​

如果项目还没有 GitHub 仓库：

  1. 访问 https://github.com/organizations/secure-artifacts/repositories/new
  2. 填写项目名称和描述
  3. 选择 Public 或 Private
  4. 创建仓库后，按照页面提示推送代码：
bash
git remote add origin https://github.com/secure-artifacts/your-project.git
git branch -M main
git push -u origin main

方式三：转移现有项目 ​

  1. 进入项目 Settings
  2. 滚动到底部 Danger Zone
  3. 点击 Transfer repository
  4. 输入目标组织 secure-artifacts

确认点： 请用户提供组织下的项目 URL，格式应为 https://github.com/secure-artifacts/项目名。

第 4 步：配置 GitHub Actions CI ​

在项目中添加 GitHub Actions 工作流，确保构建产物带有 Attestation 签名。

4.1 创建工作流文件 ​

在项目根目录创建 .github/workflows/release.yml 文件。

以下是适用于 Node.js 项目的基础模板：

yaml
name: Build and Release

on:
  push:
    tags:
      - 'v*'

jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      id-token: write
      contents: write
      attestations: write

    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install Dependencies
        run: npm ci

      - name: Build
        run: npm run build

      - name: Attest Build Provenance
        uses: actions/attest-build-provenance@v2
        with:
          subject-path: 'dist/*'

      - name: Create Release
        uses: softprops/action-gh-release@v2
        with:
          files: dist/*
          generate_release_notes: true

4.2 关键配置说明 ​

permissions 必须包含以下三项：

yaml
permissions:
  id-token: write      # 生成 OIDC token
  contents: write      # 创建 Release
  attestations: write  # 生成 Attestation

Attestation 步骤说明：

yaml
- name: Attest Build Provenance
  uses: actions/attest-build-provenance@v2
  with:
    subject-path: 'dist/*'  # 指向构建产物路径

subject-path 应指向项目的构建产物目录，根据实际项目调整。

4.3 其他语言/框架模板 ​

  • Python 项目 - 将 Setup Node.js 替换为 Setup Python，将 npm ci && npm run build 替换为 pip install build && python -m build
  • Go 项目 - 使用 actions/setup-go，运行 go build
  • Electron 应用 - 需要多平台构建矩阵

更多模板请参考：完整 Workflow 示例

4.4 提交工作流文件 ​

bash
git add .github/workflows/release.yml
git commit -m "Add release workflow with attestation"
git push origin main

确认点： 请用户确认已将工作流文件推送到 GitHub 仓库。

第 5 步：提交安全审核 ​

项目配置完成后，提交安全审核申请。

  1. 打开安全管理平台：https://security-platform-web.vercel.app
  2. 选择 "提交项目审核" 流程
  3. 填写以下信息：
    • GitHub 项目 URL - 必须以 https://github.com/secure-artifacts/ 开头
    • 项目名称 - 项目的显示名称
    • 项目描述 - 简要描述项目功能和用途
    • Teams 链接 - Microsoft Teams 联系链接
    • 提交者邮箱 - 工作邮箱
  4. 点击提交

审核流程 ​

提交后，管理员会进行以下审核：

  1. 自动预检 - 检查基本安全要求，自动开启 Secret Scanning 和 Push Protection
  2. 人工审核 - 管理员审核代码，手动开启 Code Scanning (CodeQL)
  3. 结果通知 - 通过 Teams 通知审核结果

审核通常在 1-3 个工作日内完成。

确认点： 请用户确认已提交审核申请，并告知用户等待管理员通知。

发布新版本 ​

审核通过后，每次发布新版本只需创建一个 Git Tag：

bash
# 创建版本 tag
git tag -a v1.0.0 -m "Release version 1.0.0"

# 推送 tag 触发自动构建
git push origin v1.0.0

推送 tag 后，GitHub Actions 会自动构建、签名并发布到 Release 页面。

验证发布 ​

用户可以使用以下命令验证已发布的软件：

bash
# 安装 GitHub CLI（如果未安装）
# macOS: brew install gh
# Windows: winget install GitHub.cli

# 验证软件来源
gh attestation verify ./下载的文件 --repo secure-artifacts/项目名

常见问题 ​

Q: GitHub Actions 构建失败怎么办？ ​

  1. 进入仓库的 Actions 页面查看失败日志
  2. 修复代码问题
  3. 删除失败的 tag 并重新创建：
bash
git tag -d v1.0.0
git push origin :refs/tags/v1.0.0
git tag -a v1.0.0 -m "Release version 1.0.0"
git push origin v1.0.0

Q: 项目审核不通过怎么办？ ​

管理员会通过 Teams 说明不通过的原因。修复问题后可以重新提交审核。

Q: 可以在审核前先测试构建流程吗？ ​

可以。配置好工作流后，创建一个测试 tag（如 v0.0.1-test）验证构建流程是否正常。

Q: permissions 中的三个权限分别是什么作用？ ​

  • id-token: write - 让 GitHub Actions 生成 OIDC token，用于 Attestation 签名
  • contents: write - 允许创建 GitHub Release
  • attestations: write - 允许生成和存储 Attestation 记录