Jenkins 注册

更新时间:
复制 MD 格式

在 Jenkins 流水线中运行 codesec-cli,可自动接入代码安全的源码扫描能力,包括静态应用安全测试(SAST)、软件成分分析(Software Composition Analysis,SCA)、Secret(敏感信息)检测和基础设施即代码(IaC)。本文介绍如何配置合并请求增量卡点扫描和主干分支全量基线扫描,并将扫描结果回写到合并请求评论或在代码安全控制台统一查看。

接入流程分为五步:准备阿里云访问凭证、在 Jenkins 登记凭据、配置 Jenkins 流水线和触发器、在代码平台配置 Webhook,以及触发构建验证接入。

步骤

名称

主要动作

操作位置

一

获取凭证

创建 RAM 权限策略和用户,获取 AccessKey

阿里云 RAM 控制台

二

配置凭据

将 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

对应环境变量

取值

说明

codesec-ak

YUNDUN_CODESEC_OPENAPI_AK

LTAI5tXxx...

步骤一创建的 AccessKey ID。

codesec-sk

YUNDUN_CODESEC_OPENAPI_SECRET

xxxxxxxx...

步骤一创建的 AccessKey Secret。

codesec-endpoint

YUNDUN_CODESEC_OPENAPI_ENDPOINT

https://codesec.cn-hangzhou.aliyuncs.com

代码安全 OpenAPI 网关地址。

gitlab-git-cred

—

用户名和 Token 或密码

用于 Pipeline 拉取代码,Kind 选择 Username with password。

添加选填凭据

凭据 ID

对应环境变量

取值

使用条件

codesec-gitlab-token

YUNDUN_CODESEC_GITLAB_TOKEN

glpat-xxxx...

仅在使用 --comment 回写合并请求评论时需要。

重要

GitLab Plugin 使用的 GitLab API token 类型仅供插件使用。Pipeline 中的 credentials() 只能将 Secret text 类型的凭据绑定到环境变量。因此,即使 token 值相同,也需要额外创建一份 Secret text 类型的凭据。

步骤三:配置扫描任务

新建 Pipeline 任务

在 Jenkins 首页单击 New Item,填写任务名称 codesec-scan,选择 Pipeline,然后单击 OK。

配置构建触发器

在任务配置页的 Build Triggers 区域完成以下配置:

  1. 勾选 Build when a change is pushed to GitLab。

  2. 在展开选项中勾选 Opened Merge Request Events 和 Accepted Merge Request Events,使合并请求也可以触发构建。

  3. 记录页面显示的 Webhook URL,格式为 http://<jenkins-host>:8080/project/codesec-scan。

  4. 单击 Advanced,生成并复制 Secret token。步骤四需要将该 token 粘贴到代码平台。

  5. 在同一 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 不匹配时,请求按匿名用户权限处理,并返回 403 anonymous is missing the Job/Build permission。

插件会验证 Secret token:token 匹配时,以系统权限触发构建。

选择扫描策略

建议同时启用增量卡点扫描和全量基线扫描,形成增量卡点与全量兜底的组合。

策略

触发时机

扫描范围

结果去向

增量卡点扫描

创建或更新目标为主干分支的合并请求

仅本次变更涉及的代码

回写为合并请求评论;发现高危问题时,构建失败。

全量基线扫描

主干分支 push

仓库中的全部代码

输出 JSON 和 SARIF 报告并归档。

选择执行方式

Jenkins 支持以下两种执行 codesec-cli 的方式,请任选一种。

对比项

方式 A:二进制直装(推荐)

方式 B:容器镜像

原理

将 codesec-cli 预装到 Jenkins 镜像或构建节点中,由 Pipeline 直接执行。

在 Pipeline 中通过 docker run 启动 codesec-cli 容器。

路径映射

无需处理。

Jenkins 容器化部署时,需要处理宿主机路径映射。

凭据传递

credentials() 注入的环境变量可直接被 shell 进程读取。

需要通过 -e 将环境变量逐项传入容器。

版本升级

需要重新构建镜像或重新安装二进制文件。

修改镜像 tag 即可。

Docker 依赖

无需访问 Docker daemon。

需要挂载 docker.sock 并处理权限。

方式 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,完成以下配置:

  1. 在 URL 中填写步骤三记录的 Jenkins Webhook 地址。

  2. 在 Secret token 中粘贴步骤三生成的 token。此项为必填项,缺失会导致 403。

  3. 勾选 Push events,并在展开的 Branch filter 中填写主干分支名称。

  4. 勾选 Merge request events。该事件不受 Branch filter 影响。

  5. 如果内网环境未使用 HTTPS,取消勾选 Enable SSL verification。

  6. 保存后,单击 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 上报,可登录代码安全控制台统一查看。