GitLab 注册
通过 GitLab 注册,可将代码安全扫描集成到 GitLab CI/CD 流程中。代码合入默认分支或创建 Merge Request(MR)时,系统自动执行扫描并将结果以评论形式展示在 MR 页面,帮助团队在代码合并前发现和修复安全漏洞。
背景信息
自动注册项目适用于代码托管在 GitLab 的开发团队,可将安全检测融入日常开发工作流,无需手动上传代码压缩包。
与手动创建项目相比,自动注册项目更适合持续集成场景:
对比项 | 自动注册项目 | 手动创建项目 |
适用场景 | 代码托管在 GitLab,需持续集成安全检测 | 代码未托管在 Git 仓库,或需一次性、临时性扫描 |
触发方式 | 代码合入默认分支或创建 MR 时自动触发 | 手动上传代码压缩包触发扫描 |
适用对象 | DevOps 工程师、持续集成团队 | 开发者、安全团队临时检测 |
自动注册项目支持两种扫描能力,能力说明请分别参见静态应用安全测试(SAST)和软件成分分析(SCA)。
前提条件
已开通代码安全服务。
拥有阿里云账号的 RAM 管理权限,用于创建访问凭证。
拥有 GitLab 实例的管理权限(Premium / Ultimate 版本或 CE 免费版),用于配置 CI/CD 变量和 Pipeline。
GitLab Runner 已部署并可正常使用。
步骤一:创建项目并进入引导页面
登录代码安全控制台。
在项目列表页面,单击创建项目。
从弹出的菜单选择自动注册。
系统自动跳转至 GitLab CI 接入向导 页面。
引导页面包含四个步骤:获取凭证、扫描配置、配置变量、验证接入。请按下文步骤依次完成配置。
步骤二:获取 AccessKey 凭证
需要在 RAM 控制台创建具有代码安全服务权限的 RAM 用户,并获取 AccessKey ID 和 AccessKey Secret。该步骤对应向导的获取凭证步骤。
创建权限策略
登录 RAM 访问控制 控制台。
在左侧导航栏选择权限管理 > 权限策略。
单击创建权限策略,选择脚本编辑模式,输入以下策略内容后保存:
{ "Version": "1", "Statement": [ { "Effect": "Allow", "Action": "yundun-codesec:*", "Resource": "*" } ] }
创建 RAM 用户
在左侧导航栏选择身份管理 > 用户,单击创建用户。
在访问方式下勾选使用永久 AccessKey 访问,完成用户创建。
创建完成后,立即保存 AccessKey ID 和 AccessKey Secret。页面关闭后将无法再次查看。
关联权限策略
从用户列表找到刚创建的 RAM 用户,单击添加权限。
选择上一步创建的自定义策略并完成关联。
完成上述操作后,在向导页面单击下一步进入扫描配置。
步骤三:扫描配置
在向导的扫描配置步骤,根据业务需要完成以下配置。
GitLab 版本
选择 GitLab 版本类型:
Premium / Ultimate:企业版 GitLab,支持增量扫描和全量扫描。
CE 免费版:社区版 GitLab,支持基础扫描功能。
扫描策略(至少选中一个)
分支合入扫描:创建 MR 时自动触发扫描,快速验证变更代码安全性。
全量扫描:代码 Push 到默认分支时触发全量扫描,确保主分支安全基线。
扫描范围
指定项目:仅对指定的 GitLab 项目启用扫描,需在对应仓库配置 CI 文件。
全量覆盖:覆盖 GitLab 中所有项目。
GitLab Runner 配置
根据 Runner 类型选择对应的 Executor(已注册的 Runner 信息见项目 Settings > CI/CD > Runners):
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。
全局变量(实例级)
打开 GitLab 的 Admin Area > Settings > CI/CD > Variables(实例级,所有项目共享),配置以下变量:
变量名 | 说明 | 配置要求 |
| RAM 用户的 AccessKey ID。 | 必填,必须勾选 Masked。 |
| RAM 用户的 AccessKey Secret。 | 必填,必须勾选 Masked。 |
| 代码安全服务的 OpenAPI 接入地址。 | 必填,以向导页面给出的地址为准。 |
| 设置为 | 自签名证书时必须配置,否则 Job 在 clone 阶段即失败。 |
项目级变量
打开各项目的 Settings > CI/CD > Variables,配置以下变量:
变量名 | 说明 | 配置要求 |
| GitLab Access Token,用于在 MR 页面发布扫描结果评论。 | Token 需具有 |
安全提示:
YUNDUN_CODESEC_OPENAPI_AK和YUNDUN_CODESEC_OPENAPI_SECRET必须勾选 Masked,防止 CI 日志泄露。建议不要勾选 Protected:MR Pipeline 运行在 feature 分支上,Protected 变量仅对受保护分支的 Pipeline 可用,会导致 MR 扫描读不到凭证。
未配置
YUNDUN_CODESEC_GITLAB_TOKEN时,MR 评论不生效,但不影响扫描和报告生成。完成变量配置后,先按步骤五在 GitLab 侧部署扫描 Job,完成后单击下一步进入验证接入。
步骤五:部署安全扫描 Job
本步骤为 GitLab 侧操作,不属于向导页面流程,按扫描范围选择对应的部署方式。选择指定项目时,为目标项目根目录的 .gitlab-ci.yml 文件添加安全扫描 Job;选择全量覆盖时,由管理员按步骤三的部署说明,将向导生成的 YAML 保存为实例级模板。扫描 Job 的 YAML 定义示例如下:
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)。验证通过后,单击完成退出向导。