Jenkins 注册
在 Jenkins 流水线中运行 codesec-cli,可自动接入代码安全的源码扫描能力,包括静态应用安全测试(SAST)、软件成分分析(Software Composition Analysis,SCA)、Secret(敏感信息)检测和基础设施即代码(IaC)。本文介绍如何配置合并请求增量卡点扫描和主干分支全量基线扫描,并将扫描结果回写到合并请求评论或在代码安全控制台统一查看。
接入流程分为五步:准备阿里云访问凭证、在 Jenkins 登记凭据、配置 Jenkins 流水线和触发器、在代码平台配置 Webhook,以及触发构建验证接入。
|
步骤 |
名称 |
主要动作 |
操作位置 |
|
一 |
获取凭证 |
创建 RAM 权限策略和用户,获取 AccessKey |
|
|
二 |
配置凭据 |
将 AK/SK、Endpoint 和 Token 登记为 Jenkins 凭据 |
Jenkins 凭据管理 |
|
三 |
配置扫描任务 |
新建 Pipeline、配置触发器和扫描脚本 |
Jenkins |
|
四 |
配置代码平台 Webhook |
登记 Webhook 地址、Secret token 和触发事件 |
代码平台 |
|
五 |
验证接入 |
手动构建,以及通过 Push 或合并请求触发构建并查看扫描结果 |
Jenkins 和代码安全控制台 |
开始前准备
-
Jenkins 版本为 2.361 或更高版本。
-
已安装 GitLab Plugin、Pipeline 和 Git 相关插件。
-
Jenkins 构建节点可访问公网,以调用代码安全 OpenAPI。
-
已准备接入扫描的 Git 代码仓库,且具备在代码平台配置 Webhook 的权限;如果代码平台限制 Webhook 访问内网地址,还需具备 Admin Area 的配置权限。
-
如果选择容器镜像方式执行扫描,构建环境需可访问 Docker daemon(挂载
docker.sock并处理权限)。
步骤一:获取凭证
代码安全通过 OpenAPI 上报扫描结果和拉取结果,因此需要创建具有代码安全操作权限的 RAM 用户并获取其 AccessKey。
创建自定义权限策略
登录阿里云 RAM 控制台,依次选择权限管理 > 权限策略 > 创建权限策略,选择脚本编辑,粘贴以下内容并保存。建议将策略命名为 AliyunCodeSecFullAccess。
{
"Version": "1",
"Statement": [
{
"Effect": "Allow",
"Action": "yundun-codesec:*",
"Resource": "*"
}
]
}
创建 RAM 用户并获取 AccessKey
依次选择身份管理 > 用户 > 创建用户,勾选使用永久 AccessKey 访问。创建完成后,立即保存 AccessKey ID 和 AccessKey Secret。
AccessKey Secret 仅在创建时显示一次。请在创建时保存;后续无法再次查看,只能重新创建。
为用户授权
在用户详情页单击新增授权,选择步骤一创建的自定义权限策略并完成绑定。
记录接入 Endpoint
代码安全 OpenAPI 网关地址的格式为 https://codesec.<region-id>.aliyuncs.com。华东 1(杭州)的 Endpoint 为 https://codesec.cn-hangzhou.aliyuncs.com,请在步骤二将该地址登记为凭据。
AccessKey 是长期凭证。请通过 Jenkins 凭据管理注入凭据,不要将其硬编码到 Jenkinsfile 或提交到代码仓库。
步骤二:配置凭据
在 Jenkins 中依次选择 Manage Jenkins > Credentials > Add Credentials,逐项添加以下凭据。除特别说明外,Kind 均选择 Secret text。
添加必填凭据
|
凭据 ID |
对应环境变量 |
取值 |
说明 |
|
|
|
|
步骤一创建的 AccessKey ID。 |
|
|
|
|
步骤一创建的 AccessKey Secret。 |
|
|
|
|
代码安全 OpenAPI 网关地址。 |
|
|
— |
用户名和 Token 或密码 |
用于 Pipeline 拉取代码,Kind 选择 Username with password。 |
添加选填凭据
|
凭据 ID |
对应环境变量 |
取值 |
使用条件 |
|
|
|
|
仅在使用 |
GitLab Plugin 使用的 GitLab API token 类型仅供插件使用。Pipeline 中的 credentials() 只能将 Secret text 类型的凭据绑定到环境变量。因此,即使 token 值相同,也需要额外创建一份 Secret text 类型的凭据。
步骤三:配置扫描任务
新建 Pipeline 任务
在 Jenkins 首页单击 New Item,填写任务名称 codesec-scan,选择 Pipeline,然后单击 OK。
配置构建触发器
在任务配置页的 Build Triggers 区域完成以下配置:
-
勾选 Build when a change is pushed to GitLab。
-
在展开选项中勾选 Opened Merge Request Events 和 Accepted Merge Request Events,使合并请求也可以触发构建。
-
记录页面显示的 Webhook URL,格式为
http://<jenkins-host>:8080/project/codesec-scan。 -
单击 Advanced,生成并复制 Secret token。步骤四需要将该 token 粘贴到代码平台。
-
在同一 Advanced 区域,找到 Allowed branches,选择 Filter branches by name,并在 Include 中填写主干分支名称,例如
main。
Allowed branches 决定只有主干分支的 push 可以触发全量构建,其他分支的 push 会被插件忽略。合并请求事件不受此过滤规则影响,仍会触发增量扫描。
Webhook 能否成功触发构建,取决于以下 Jenkins 安全配置:
|
配置项 |
位置 |
未配置的后果 |
|
允许匿名读取访问 |
Manage Jenkins > Configure Global Security > Authorization,勾选 Allow anonymous read access |
Webhook 以匿名身份发送 POST 请求,请求会在到达插件前被拦截并返回 404。 |
|
Secret token 保持一致 |
将 Jenkins 生成的 token 原样粘贴到代码平台 Webhook 的 Secret token 字段 |
token 不匹配时,请求按匿名用户权限处理,并返回 |
插件会验证 Secret token:token 匹配时,以系统权限触发构建。
选择扫描策略
建议同时启用增量卡点扫描和全量基线扫描,形成增量卡点与全量兜底的组合。
|
策略 |
触发时机 |
扫描范围 |
结果去向 |
|
增量卡点扫描 |
创建或更新目标为主干分支的合并请求 |
仅本次变更涉及的代码 |
回写为合并请求评论;发现高危问题时,构建失败。 |
|
全量基线扫描 |
主干分支 push |
仓库中的全部代码 |
输出 JSON 和 SARIF 报告并归档。 |
选择执行方式
Jenkins 支持以下两种执行 codesec-cli 的方式,请任选一种。
|
对比项 |
方式 A:二进制直装(推荐) |
方式 B:容器镜像 |
|
原理 |
将 codesec-cli 预装到 Jenkins 镜像或构建节点中,由 Pipeline 直接执行。 |
在 Pipeline 中通过 |
|
路径映射 |
无需处理。 |
Jenkins 容器化部署时,需要处理宿主机路径映射。 |
|
凭据传递 |
|
需要通过 |
|
版本升级 |
需要重新构建镜像或重新安装二进制文件。 |
修改镜像 tag 即可。 |
|
Docker 依赖 |
无需访问 Docker daemon。 |
需要挂载 |
方式 A 的准备操作如下:在 Jenkins 构建节点或自定义镜像中安装 codesec-cli。
# 从官方镜像中提取二进制
docker run --rm -v $(pwd):/out \
codesec-cli-registry.cn-hangzhou.cr.aliyuncs.com/codesec-cli/codesec-cli:latest \
cp /usr/local/bin/codesec-cli /out/codesec-cli
# 写入 Jenkins 自定义镜像 Dockerfile(USER root 段)
COPY codesec-cli /usr/local/bin/codesec-cli
RUN chmod +x /usr/local/bin/codesec-cli
二进制文件必须与构建节点的系统架构匹配,默认架构为 linux/amd64。
配置 Pipeline 脚本:二进制直装
在任务配置页底部的 Pipeline 区域,将 Definition 设置为 Pipeline script,粘贴以下脚本;粘贴前,将脚本中的尖括号占位符(如 <gitlab-host>、<group>、<project>)替换为实际值。脚本会根据触发来源自动选择扫描方式:主干分支 push 执行全量扫描,合并请求执行增量扫描并回写评论,其他场景跳过扫描。脚本内的分支守卫与构建触发器中的 Allowed branches 形成两层过滤:Allowed branches 仅在插件层过滤 push 事件,分支守卫在脚本层兼顾合并请求目标分支的校验,共同确保仅主干分支 push 或目标为主干分支的合并请求执行扫描。
pipeline {
agent any
environment {
GIT_REPO = 'http://<gitlab-host>/<group>/<project>.git'
MAIN_BRANCH = 'main'
REPORT_DIR = 'codesec-report'
GITLAB_API = 'http://<gitlab-host>/api/v4'
// credentials() 注入为进程环境变量,codesec-cli 直接读取
YUNDUN_CODESEC_OPENAPI_AK = credentials('codesec-ak')
YUNDUN_CODESEC_OPENAPI_SECRET = credentials('codesec-sk')
YUNDUN_CODESEC_OPENAPI_ENDPOINT = credentials('codesec-endpoint')
YUNDUN_CODESEC_GITLAB_TOKEN = credentials('codesec-gitlab-token')
}
stages {
stage('Checkout') {
steps {
git branch: "${env.gitlabSourceBranch ?: env.MAIN_BRANCH}",
url: "${GIT_REPO}",
credentialsId: 'gitlab-git-cred'
}
}
stage('CodeSec Scan') {
steps {
script {
def isMR = env.gitlabMergeRequestIid != null
// 分支守卫:仅主干 push 或目标为主干的合并请求才扫描
if (!isMR && env.gitlabBranch && env.gitlabBranch != env.MAIN_BRANCH) {
echo "跳过:push 分支为 ${env.gitlabBranch},非主干分支"
return
}
if (isMR && env.gitlabTargetBranch && env.gitlabTargetBranch != env.MAIN_BRANCH) {
echo "跳过:合并请求目标分支为 ${env.gitlabTargetBranch},非主干分支"
return
}
if (isMR) {
sh """
codesec-cli scan \
--platform jenkins \
--diff --base origin/${env.gitlabTargetBranch} \
--change-id ${env.gitlabMergeRequestIid} \
--api-url ${GITLAB_API} \
--comment \
--report sarif=${REPORT_DIR}/report.sarif \
--fail-on high
"""
} else {
sh """
codesec-cli scan \
--platform jenkins \
--all \
--report json=${REPORT_DIR}/report.json \
--report sarif=${REPORT_DIR}/report.sarif \
--fail-on high
"""
}
}
}
}
stage('Archive Report') {
steps {
archiveArtifacts artifacts: 'codesec-report/**', allowEmptyArchive: true
}
}
}
post {
failure {
echo '扫描发现高危问题或执行失败,请查看归档报告'
}
}
}
使用二进制直装方式时,codesec-cli 命令至少需要 --platform jenkins 和扫描模式参数:全量扫描指定 --all;增量扫描指定 --diff,并需要 --base、--change-id 和 --api-url 参数,通过 --comment 将扫描结果回写为合并请求评论。凭据和 Endpoint 会从环境变量中自动读取;项目名称、分支和 commit 会从当前目录的 .git/ 中自动推断。
配置 Pipeline 脚本:容器镜像
容器镜像方式与二进制直装方式的差异集中在扫描阶段:需要将工作区挂载到容器中,并逐项传递环境变量。脚本中的 <宿主机 jenkins_home 路径> 等占位符同样需要替换为实际值。
pipeline {
agent any
environment {
GIT_REPO = 'http://<gitlab-host>/<group>/<project>.git'
MAIN_BRANCH = 'main'
CODESEC_IMAGE = 'codesec-cli-registry.cn-hangzhou.cr.aliyuncs.com/codesec-cli/codesec-cli:latest'
REPORT_DIR = '/src/codesec-report'
GITLAB_API = 'http://<gitlab-host>/api/v4'
// 仅当 Jenkins 自身运行在容器中时需要:指向宿主机上 jenkins_home 的挂载点
JENKINS_HOME_HOST = '<宿主机 jenkins_home 路径>'
YUNDUN_CODESEC_OPENAPI_AK = credentials('codesec-ak')
YUNDUN_CODESEC_OPENAPI_SECRET = credentials('codesec-sk')
YUNDUN_CODESEC_OPENAPI_ENDPOINT = credentials('codesec-endpoint')
YUNDUN_CODESEC_GITLAB_TOKEN = credentials('codesec-gitlab-token')
}
stages {
stage('Checkout') {
steps {
git branch: "${env.gitlabSourceBranch ?: env.MAIN_BRANCH}",
url: "${GIT_REPO}",
credentialsId: 'gitlab-git-cred'
}
}
stage('CodeSec Scan') {
steps {
script {
// Jenkins 容器化部署时,需把容器内 WORKSPACE 换算为宿主机真实路径
def hostWorkspace = "${WORKSPACE}".replace('/var/jenkins_home', "${JENKINS_HOME_HOST}")
def isMR = env.gitlabMergeRequestIid != null
if (!isMR && env.gitlabBranch && env.gitlabBranch != env.MAIN_BRANCH) {
echo "跳过:push 分支为 ${env.gitlabBranch},非主干分支"
return
}
if (isMR && env.gitlabTargetBranch && env.gitlabTargetBranch != env.MAIN_BRANCH) {
echo "跳过:合并请求目标分支为 ${env.gitlabTargetBranch},非主干分支"
return
}
def scanCmd = isMR \
? "codesec-cli scan --platform jenkins --diff --base origin/${env.gitlabTargetBranch} --change-id ${env.gitlabMergeRequestIid} --api-url ${GITLAB_API} --comment --report sarif=${REPORT_DIR}/report.sarif --fail-on high" \
: "codesec-cli scan --platform jenkins --all --report json=${REPORT_DIR}/report.json --report sarif=${REPORT_DIR}/report.sarif --fail-on high"
sh """
docker run --rm \
-v ${hostWorkspace}:/src \
-w /src \
-e YUNDUN_CODESEC_OPENAPI_AK=\${YUNDUN_CODESEC_OPENAPI_AK} \
-e YUNDUN_CODESEC_OPENAPI_SECRET=\${YUNDUN_CODESEC_OPENAPI_SECRET} \
-e YUNDUN_CODESEC_OPENAPI_ENDPOINT=\${YUNDUN_CODESEC_OPENAPI_ENDPOINT} \
-e YUNDUN_CODESEC_GITLAB_TOKEN=\${YUNDUN_CODESEC_GITLAB_TOKEN} \
\${CODESEC_IMAGE} \
${scanCmd}
"""
}
}
}
stage('Archive Report') {
steps {
archiveArtifacts artifacts: 'codesec-report/**', allowEmptyArchive: true
}
}
}
}
如果 Jenkins 运行在容器中,且通过挂载 docker.sock 调用宿主机 Docker,${WORKSPACE} 是 Jenkins 容器内的路径,而 Docker daemon 会在宿主机上解析该路径。若不换算,Docker 会挂载不存在的空目录,扫描结果为 No scannable files.。如果 Jenkins 直接部署在物理机或虚拟机上,无需换算,直接使用 ${WORKSPACE} 即可。
步骤四:配置代码平台 Webhook
在代码仓库中依次选择 Settings > Webhooks,完成以下配置:
-
在 URL 中填写步骤三记录的 Jenkins Webhook 地址。
-
在 Secret token 中粘贴步骤三生成的 token。此项为必填项,缺失会导致 403。
-
勾选 Push events,并在展开的 Branch filter 中填写主干分支名称。
-
勾选 Merge request events。该事件不受 Branch filter 影响。
-
如果内网环境未使用 HTTPS,取消勾选 Enable SSL verification。
-
保存后,单击 Test > Push events 发起验证,请求应返回 HTTP 200。
如果 Webhook 页面提示 URL is blocked,请在代码平台中依次选择 Admin Area > Settings > Network > Outbound requests,允许 Webhook 访问内网地址。
步骤五:验证接入
手动触发构建
在 Jenkins 任务页面单击 Build Now,并在 Console Output 中查看执行结果。正常输出示例如下:
[Pipeline] stage (Checkout)
Cloning repository http://<gitlab-host>/<group>/<project>.git
[Pipeline] stage (CodeSec Scan)
[codesec-cli] Starting full scan...
[codesec-cli] Scan completed. Found X issues.
[Pipeline] stage (Archive Report)
Archiving artifacts
验证自动触发
向主干分支推送一次提交,验证 push 是否可以自动触发构建。示例如下:
git clone http://<gitlab-host>/<group>/<project>.git
cd <project>
echo "// security test" >> README.md
git add . && git commit -m "trigger security scan"
git push origin main
推送后,Jenkins 应自动触发构建。对于合并请求场景,请新建一个目标为主干分支的合并请求;构建完成后,应在合并请求页面看到扫描结果评论。此外,扫描结果会通过 OpenAPI 上报,可登录代码安全控制台统一查看。