安全扫描功能说明

本文档面向管理员

安全扫描功能由管理员在审核流程中统一配置。开发者无需自行开启，提交项目审核后管理员会自动处理。

自动开启的功能

在管理员执行安全预检时，以下功能会通过 GitHub API 自动开启：

功能	方式	说明
Secret Scanning	自动开启	扫描仓库中已存在的密钥和凭证
Push Protection	自动开启	在推送时阻止包含密钥的提交

预检流程会调用 GitHub API 自动启用 Secret Scanning 和 Push Protection，无需任何手动操作。

需要手动开启的功能

Code Scanning (CodeQL) 无法通过 API 自动开启，需要管理员手动在 GitHub Settings 中配置。

Swift 项目不要使用 Default 模式

Swift 项目必须走 Advanced CodeQL workflow，不要在 GitHub Code scanning 中启用 Default setup。若 Default setup 与仓库内 .github/workflows/codeql.yml 同时存在，GitHub 会报错：CodeQL analyses from advanced configurations cannot be processed when the default setup is enabled。

审核 Swift 项目时，管理员应检查仓库是否存在 .github/workflows/codeql.yml，并确认该 workflow 已成功运行。若缺失或失败，请让用户按 CodeQL workflow（Swift - Xcode 工程） 或同页 Swift SPM 模板配置。

操作步骤

管理员在预检结果中如果看到 Code Scanning 未开启，可以点击预检弹窗底部的「开启 Code Scanning」按钮，系统会在新窗口打开对应仓库的安全设置页面。

以下是在 GitHub 上手动开启 CodeQL Default setup 的详细步骤，仅适用于非 Swift 项目：

第 1 步：进入项目设置

打开 GitHub 项目页面，点击顶部导航栏中的 Settings（设置）选项卡。

第 2 步：进入 Advanced Security 页面

在 Settings 左侧菜单中，找到 Security 分组下的 Advanced Security，点击进入。

第 3 步：找到 Code Scanning 区域

向下滚动页面，找到 Code scanning 区域。在 CodeQL analysis 部分，点击 Set up 按钮。

第 4 步：选择 Default 配置

在弹出的下拉菜单中，选择 Default。Default 模式会自动为仓库选择最佳配置，适合大多数项目。

Default vs Advanced：

• Default：CodeQL 自动检测仓库语言并应用高精度查询规则，无需额外配置
• Advanced：通过 YAML 文件自定义 CodeQL 配置，适合有特殊需求的项目

第 5 步：确认并启用 CodeQL

在弹出的配置对话框中，确认配置无误后，点击绿色的 Enable CodeQL 按钮。

第 6 步：启用成功

CodeQL analysis 状态会变为 Setting up，表示正在进行首次全量扫描。首次扫描完成后，按钮状态会变为 Enabled。

功能说明

功能	作用	开启方式
Code Scanning (CodeQL)	自动检测代码漏洞和编码错误	管理员手动开启
Secret Scanning	扫描仓库中已存在的密钥和凭证	预检时自动开启
Push Protection	在推送时阻止包含密钥的提交	预检时自动开启

后续说明

• Code Scanning 首次扫描可能需要几分钟时间，扫描完成后可以在 Security 选项卡中查看结果
• 扫描发现的问题会以 Alert 形式展示，建议及时修复
• 如需自定义扫描规则，可以切换到 Advanced 模式，通过 .github/workflows 目录下的 YAML 文件进行配置