代码安全：自动注册项目

通过自动注册项目，将代码安全扫描集成到 GitLab CI/CD 流程中，实现代码提交时自动触发安全检测。代码合入默认分支或创建 Merge Request（MR）时，系统自动执行扫描并将结果以评论形式展示在 MR 页面，帮助团队在代码合并前发现和修复安全漏洞。

背景信息

自动注册项目适用于代码托管在 GitLab 的开发团队，通过 GitLab CI/CD 流程自动触发代码安全扫描，将安全检测融入日常开发工作流，无需手动上传代码压缩包。

与手动上传扫描相比，自动注册项目更适合持续集成场景：

对比项	自动注册项目	手动创建项目
适用场景	代码托管在 GitLab，需持续集成安全检测	代码未托管在 Git 仓库，或需一次性、临时性扫描
触发方式	代码合入默认分支或创建 MR 时自动触发	手动上传代码压缩包触发扫描
适用对象	DevOps 工程师、持续集成团队	开发者、安全团队临时检测

自动注册项目支持两种扫描能力：静态应用安全测试（SAST）与软件成分分析（SCA）。两者的能力说明请分别参见静态应用安全测试 SAST和软件成分分析 SCA。

前提条件

已开通代码安全服务。
拥有阿里云账号的 RAM 管理权限，用于创建访问凭证。
拥有 GitLab 实例的管理权限（Premium / Ultimate 版本或 CE 免费版），用于配置 CI/CD 变量和 Pipeline。
GitLab Runner 已部署并可正常使用。

步骤一：创建项目并进入引导页面

登录代码安全控制台。
在项目列表页面，单击新建项目。
在弹出的菜单中选择自动注册。
系统自动跳转至GitLab CI 接入向导页面。

引导页面包含四个步骤：获取凭证、扫描配置、配置变量、验证接入。请按下文步骤依次完成配置。

步骤二：获取 AK/SK 凭证

您需要在 RAM 控制台中创建具有代码安全服务权限的子账号，并获取 AccessKey ID 和 AccessKey Secret。该步骤对应向导中的获取凭证步骤。

创建权限策略

登录RAM 访问控制控制台。
在左侧导航栏选择权限管理 > 权限策略。

单击创建权限策略，选择脚本编辑模式，输入以下策略内容后保存：

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "yundun-codesec:*",
      "Resource": "*"
    }
  ]
}

创建 RAM 子账号

在左侧导航栏选择身份管理 > 用户，单击创建用户。
在访问方式中勾选使用永久 AccessKey 访问，完成用户创建。
创建完成后，立即保存 AccessKey ID 和 AccessKey Secret。页面关闭后将无法再次查看。

关联权限策略

在用户列表中找到刚创建的子账号，单击添加权限。
选择上一步创建的自定义策略并完成关联。

完成上述操作后，在向导页面单击下一步进入扫描配置。

步骤三：扫描配置

在向导的扫描配置步骤，根据业务需要完成以下配置。

GitLab 版本

选择您的 GitLab 版本类型：

Premium / Ultimate：企业版 GitLab，支持增量扫描和全量扫描。
CE 免费版：社区版 GitLab，支持基础扫描功能。

扫描策略（至少选中一个）

分支合入扫描：创建 MR 时自动触发扫描，快速验证变更代码安全性。
全量扫描：代码 Push 到默认分支时触发全量扫描，确保主分支安全基线。

扫描范围

指定项目：仅对指定的 GitLab 项目启用扫描，需在对应仓库配置 CI 文件。
全量覆盖：覆盖 GitLab 中所有项目。

GitLab Runner 配置

根据您的 Runner 类型选择对应的 Executor（可在项目 Settings > CI/CD > Runners 中查看已注册的 Runner 信息）：

Docker executor：推荐方式，扫描在容器中运行，Runner 必须使用 Docker executor。
Shell executor：扫描直接在 Runner 主机上运行。

无论选择哪种 Executor，Runner 都需能访问公网，以拉取扫描镜像并上传结果。

部署说明

系统会根据上述选择动态生成对应的部署说明和 YAML 模板。以全量覆盖（Admin 操作）模式为例：

在 GitLab 上创建模板仓库（如 yundun-codesec/templates），将向导给出的 YAML 保存为 yundun-codesec-config.yml。
进入 Admin Area > Settings > CI/CD > Required pipeline configuration。
填写模板路径：yundun-codesec-config.yml@yundun-codesec/templates。
保存后，所有项目的 Pipeline 自动包含扫描 Job。
个别项目豁免：在该项目的 CI/CD Variables 中添加 YUNDUN_CODESEC_SKIP=true。

完成扫描配置后，单击下一步进入变量配置。

步骤四：配置 CI/CD 变量

在向导的配置变量步骤，按说明在 GitLab 中配置 CI/CD 变量，用于扫描工具连接代码安全服务和 GitLab API。

全局变量（实例级或 Group 级）

在 GitLab 的 Admin Area > Settings > CI/CD > Variables（实例级，所有项目共享）中配置以下变量：

变量名	说明	配置要求
YUNDUN_CODESEC_OPENAPI_AK	RAM 子账号的 AccessKey ID。	必填，必须勾选 Masked。
YUNDUN_CODESEC_OPENAPI_SECRET	RAM 子账号的 AccessKey Secret。	必填，必须勾选 Masked。
YUNDUN_CODESEC_OPENAPI_ENDPOINT	代码安全服务的 OpenAPI 接入地址。	必填，以向导页面给出的地址为准。
GIT_SSL_NO_VERIFY	设置为 `true` 可跳过 TLS 证书校验。	自签名证书时必须配置，否则 Job 在 clone 阶段即失败。

项目级变量

在各项目的 Settings > CI/CD > Variables 中配置以下变量：

变量名	说明	配置要求
YUNDUN_CODESEC_GITLAB_TOKEN	GitLab Access Token，用于在 MR 页面发布扫描结果评论。	Token 需具有 api 权限。推荐使用 Project Access Token（Settings > Access Tokens，角色 Developer）。

重要

安全提示：

YUNDUN_CODESEC_OPENAPI_AK 和 YUNDUN_CODESEC_OPENAPI_SECRET 必须勾选 Masked，防止在 CI 日志中泄露。
建议不要勾选 Protected：MR Pipeline 运行在 feature 分支上，Protected 变量仅在受保护分支的 Pipeline 中可用，会导致 MR 扫描读不到凭证。
未配置 YUNDUN_CODESEC_GITLAB_TOKEN 时，MR 评论不生效，但不影响扫描和报告生成。

完成变量配置后，单击下一步进入验证接入。

步骤五：配置 .gitlab-ci.yml

在项目根目录的 .gitlab-ci.yml 文件中添加安全扫描 Job。以全量覆盖模式为例：

stages:
  - security

yundun-codesec-scan:
  stage: security
  image: codesec-registry.cn-hangzhou.cr.aliyuncs.com/codesec/krypton-cli:latest
  script:
    - krypton-cli scan --gl-sast-report=gl-sast-report.json --gl-dependency-scanning-report=gl-dependency-scanning-report.json --mr-comment
  artifacts:
    reports:
      sast: gl-sast-report.json
      dependency_scanning: gl-dependency-scanning-report.json
  when: always

关键参数说明：

--gl-sast-report：生成 SAST 扫描报告文件。
--gl-dependency-scanning-report：生成依赖扫描报告文件。
--mr-comment：在 MR 页面自动发布扫描结果评论。

完成后单击下一步进入验证接入。

步骤六：验证接入

在向导的验证接入步骤，通过以下方式验证接入是否成功。

触发扫描

通过以下任一方式触发扫描：

创建一个 Merge Request（触发 MR 增量扫描，快速验证变更代码安全性）。
Push 代码到默认分支（触发全量扫描，确保主分支安全基线）。

在代码安全控制台验证

登录代码安全控制台。
在项目列表中确认 GitLab 项目已出现，接入类型为 GitLab CI。
进入项目详情，查看任务列表，确认存在扫描记录。扫描完成后，可在扫描结果中查看漏洞详情、严重等级和修复建议。

在 GitLab 侧验证

在项目的 Build > Pipelines（旧版为 CI/CD > Pipelines）页面，点击最新 Pipeline，确认出现名为 yundun-codesec-scan 的 Job。
在 Job 详情页的 Artifacts 中，确认已生成 gl-sast-report.json 等扫描报告文件。
在 MR 页面确认评论区出现代码安全扫描结果评论，包含新增 / 修复漏洞汇总（需配置 YUNDUN_CODESEC_GITLAB_TOKEN）。

验证通过后，单击完成退出向导。