安全开发-DependencyTrack

前言

Rancher、Gitea、SonarQube 就位之后,还缺一环:依赖安全:程序里真正跑起来的代码,绝大部分不是我们自己写的,而是从开源仓库拉进来的依赖(例子里的 Go 程序就依赖 16 个第三方模块)。依赖里出了已知漏洞,SonarQube 扫不出来(它只看自己写的代码),需要 SCA(Software Composition Analysis,软件成分分析) 工具盯着。

这篇在内网部署 Dependency-Track(DT)(一个专门收 SBOM(软件物料清单)、持续匹配依赖漏洞的平台,然后接进 Gitea Actions 流水线,每次发版自动把 SBOM 推上去。

1 背景概念:SBOM、SCA 和 DT

1.1 SBOM:软件物料清单

现代程序 = 自己的代码 + 大量开源依赖。以 Go 为例,go.mod 声明了项目依赖哪些模块、什么版本(example 项目是 1 个直接依赖 gin 框架 + 15 个间接依赖,共 16 个)。

SBOM(Software Bill of Materials,软件物料清单) 是一份机器可读的组件清单:列出软件包含的所有组件及版本。有了它,漏洞披露时(比如“某库 1.2.3 以下有漏洞“)就能立刻回答“我用没用这个库?什么版本?受不受影响?“;没有它,就得人肉翻依赖树,间接依赖动辄上百个,翻不动。

两个配套术语:

  • CycloneDX:主流 SBOM 格式之一(JSON 或 XML,另一个主流格式是 SPDX)。DT 两种都收。
  • PURL(Package URL,包统一标识):一个软件包的全局唯一标识,如 pkg:golang/github.com/gin-gonic/[email protected]。DT 主要靠“PURL + 版本“把 SBOM 里的组件和漏洞库对起来。

1.2 SCA:不自己审计,而是查数据库

SCA 做的事:拿 SBOM 里的每个组件,去一堆漏洞数据库里比对,找出已知漏洞。相关术语:

  • CVE(Common Vulnerabilities and Exposures):漏洞的公开编号,如 CVE-2024-1234。
  • KEV(Known Exploited Vulnerabilities,已知被利用漏洞):“在真实攻击里被用过了“的漏洞精选清单。CISA(美国网络安全与基础设施安全局)发布官方 KEV 目录;组件一旦命中 KEV,修复优先级应该最高,攻击者已经在用了,不是“迟早“而是“正在”。
  • 数据源没有银弹:不同源的覆盖范围、更新速度、准确度都不一样。DT 的设计就是“多数据源、可开关“,开哪几个是工程取舍。

1.3 Dependency-Track:SBOM 的汇聚平台

DT 的职责链条:接收 SBOM(任何来源、CycloneDX/SPDX 格式)→ 维护项目与组件数据库 → 持续匹配各漏洞源 → 输出漏洞清单和组合级统计(多少项目、多少有漏洞组件、趋势如何)。

注意“持续“二字:SBOM 传一次之后不需要重复上传:DT 定期从各数据源拉新数据,新漏洞镜像下来后自动对存量组件重新匹配(官方叫 continuous analysis)。也就是说,“传一次 SBOM”= 登记了项目的依赖快照,之后 DT 替你持续盯着。

1.4 DT 和 SonarQube 的分工

SonarQubeDependency-Track
分析对象你自己写的代码(SAST 静态分析)你引用的依赖(SCA)
发现什么注入风险、逻辑缺陷、代码坏味道依赖组件的已知漏洞(CVE/KEV)
输入源代码SBOM
典型动作修代码升级依赖版本

SonarQube 本身也有一个小的依赖漏洞功能,但 DT 是专门平台:SBOM 多格式、多项目聚合、数据源可配、团队权限模型完整。分工一句话:SonarQube 看代码,DT 看依赖,两条流水线各管一段、互不干扰。

2 搭建

2.1 总体思路:要哪些组件

  • DT 本体:一个 Web 服务(Helm chart 部署的 Deployment)。
  • 数据库:PostgreSQL。不随 chart 自带,复用集群 middleware(中间件)命名空间里已在运行的共享 PostgreSQL,给 DT 建一个专属数据库。
  • 文件存储:10Gi 的 PVC(Persistent Volume Claim,持久卷声明,给 Pod 挂一块跨重启不丢的磁盘),存 DT 的文件类数据。
  • chart:官方 owasp/dependency-track Helm chart。

2.2 在共享 PostgreSQL 上建库(kubectl)

在集群节点上执行:

# 从现成的 secret 读 postgres 密码(middleware ns、postgresql 这个 release 的 secret)
#    secret 里的密码是 base64 编码存的,管道里 base64 -d 解码
export POSTGRES_PASSWORD=$(kubectl get secret --namespace middleware postgresql \
  -o jsonpath="{.data.postgres-password}" | base64 -d)

# 起一个临时 pod(bitnami postgresql-client 镜像)进去执行 psql:
#    --rm                退出后自动删 pod
#    --restart='Never'   保证不会反复重启
#    --tty -i            分配终端、接标准输入
#    --command -- ...    覆盖容器默认启动命令,直接跑 psql
kubectl run postgresql-client --rm --tty -i --restart='Never' \
  --namespace middleware \
  --image registry-1.docker.io/bitnami/postgresql:latest \
  --env="PGPASSWORD=$POSTGRES_PASSWORD" \
  --command -- psql --host postgresql -U postgres -d postgres -p 5432 \
  -c 'CREATE DATABASE dtrack;'

kubectl 本身没有 psql 客户端,所以临时起一个 postgresql-client 容器进去执行,退出后自动销毁。密码从 secret 读而不是敲在命令里(不进 shell 历史);数据库名 dtrack 随意,只要和 values 里的 URL 一致即可。

实际输出:CREATE DATABASE 一行成功提示,随后 pod 自动删除。

2.3 Helm values 改动

部署时的 values 改动(diff 形式;DT_OIDC_CLIENT_ID 的真实值与 master key 已替换为占位符,数据库密码按记录原样保留占位值 yourMasterPassword):

@@ 主容器(DT 应用)extraEnv @@
-  extraEnv: []
+  extraEnv:
+    - name: DT_DATASOURCE_DEFAULT_URL
+      value: jdbc:postgresql://postgresql.middleware.svc.cluster.local:5432/dtrack
+    - name: DT_DATASOURCE_DEFAULT_USERNAME
+      value: postgres
+    - name: DT_DATASOURCE_DEFAULT_PASSWORD
+      value: yourMasterPassword
+    - name: DT_DATASOURCE_DEFAULT_DRIVER
+      value: org.postgresql.Driver
+    - name: DT_OIDC_ENABLED
+      value: 'true'
+    - name: DT_OIDC_ISSUER
+      value: https://hub.kali-team.internal
+    - name: DT_OIDC_CLIENT_ID
+      value: <client-id>
+    - name: DT_OIDC_USERNAME_CLAIM
+      value: preferred_username
+    - name: DT_OIDC_USER_PROVISIONING
+      value: 'true'
+    - name: DT_OIDC_TEAM_SYNCHRONIZATION
+      value: 'true'
+    - name: DT_OIDC_TEAMS_CLAIM
+      value: groups
@@ chart 的 postgresql 小节 @@
   jdbcUrl: jdbc:postgresql://postgresql:5432/dtrack?reWriteBatchedInserts=true
-  password: ''
-  username: ''
+  password: 'yourMasterPassword'
+  username: 'postgres'
@@ fileStorage 小节 @@
-    storageClassName: ''
+    storageClassName: local-path
@@ chart 另一组件的 extraEnv @@
+  extraEnv:
+    - name: OIDC_ISSUER
+      value: https://hub.kali-team.internal
+    - name: OIDC_CLIENT_ID
+      value: <client-id>
+    - name: OIDC_SCOPE
+      value: openid profile email groups
@@ ingress 小节 @@
-  enabled: false
-  hostname: example.com
-  ingressClassName: ''
+  enabled: true
+  hostname: dependency-track.kali-team.internal
+  ingressClassName: traefik
@@ masterKey 小节 @@
   mode: config
-  value: ''
+  value: <master-key>
   provider: database
配置原因
数据源(DT 主容器 extraEnv)DT_DATASOURCE_DEFAULT_URL/USERNAME/PASSWORD/DRIVER 四个变量指定 JDBC 数据源。JDBC URL 拆开看:jdbc:postgresql:// 是驱动协议,postgresql.middleware.svc.cluster.local 是集群内部服务域名(middleware 是命名空间,svc.cluster.local 是固定后缀),:5432 端口,/dtrack 库名。DT 程序优先读这组环境变量,“连外部共享库“靠它实现,不用 chart 自带的库。yourMasterPassword 是记录里的占位值,实际部署时填真实库密码
OIDC 登录(同组环境变量)DT_OIDC_ENABLED=true 开启 OIDC 登录;DT_OIDC_ISSUER=https://hub.kali-team.internal 指定身份提供方(IdP,即 Gitea);DT_OIDC_CLIENT_ID 是 Gitea 侧 OAuth2 应用的客户端 ID;DT_OIDC_USERNAME_CLAIM=preferred_username 指定用令牌里的哪个字段当用户名;DT_OIDC_USER_PROVISIONING=true 首次登录自动创建用户;DT_OIDC_TEAM_SYNCHRONIZATION=true + DT_OIDC_TEAMS_CLAIM=groups 按令牌里的 groups 声明自动建/同步 DT 团队,登录后人自动进对应团队(效果见图 10)
chart 的 postgresql 小节chart 自带的 PostgreSQL 配置(jdbcUrl 指向 dtrack 库,reWriteBatchedInserts=true 是 PG 驱动参数,批量写入提速)。本环境实际生效的是上面的外部数据源 URL,这节属于 chart 基线配置,按记录保留
fileStorageprovider: local(文件存本地磁盘)+ 10Gi PVC + storageClassName: local-path(K3s 自带的本地存储类,数据落节点本地磁盘)
chart 另一组件的 extraEnvOIDC_ISSUER/OIDC_CLIENT_ID/OIDC_SCOPE(openid profile email groups),issuer 和 client 与 DT 登录配置相同,scope 额外请求组信息。这是本次部署 chart 附带的 OIDC 组件配置;chart 版本没有这一节时无需配置
ingressenabled: true + hostname: dependency-track.kali-team.internal + ingressClassName: traefik,走 Traefik 网关对内网暴露
masterKeyDT 的“主密钥“,用来加密数据库里的敏感数据(API token 等)。一旦丢失,已加密的数据无法恢复,必须固定在 values 里并妥善保存(和库密码同一安全等级),本文一律占位符 <master-key>。provider: database 表示主密钥与数据库绑定存放

2.4 安装

# release 名/命名空间自行选择;values.yaml 即 2.3 的完整 values
helm upgrade --install dependency-track owasp/dependency-track \
  --namespace <namespace> --create-namespace \
  -f values.yaml

安装完成后,浏览器访问 https://dependency-track.kali-team.internal(内网域名,/etc/hosts 已登记)。

3 首次登录与初始配置

3.1 进门先改 admin 密码

DT 首次访问会强制改初始 admin 密码(图 1):默认密码是公开信息,不改等于把管理账号暴露在明处。

首次登录改密码

图 1:DT 首次访问的改密码页(Update Password):用初始 admin 账号密码登录后必须设置新密码

3.2 面板与基本设置

改完密码进入面板(图 2,此时还是英文界面)。左侧导航分三大块:PORTFOLIO(项目/组件/漏洞/许可证/标签)、GLOBAL AUDIT(全局审计)、ADMINISTRATION(策略管理、系统设置)。

DT 面板

图 2:DT 面板(Dashboard):四个统计卡片初始都是 0(还没有项目上传 SBOM)

系统设置 → 基本设置(图 3):

  • 基础 URL:填 https://dependency-track.kali-team.internal 并点右侧校验(绿色对勾 = 验证通过)。DT 用它生成对外链接(徽章、通知里的地址等)。
  • 默认语言:ZH(中文)。保存后整个界面转中文(图 4 起即中文界面)。

基本设置

图 3:系统设置-基本设置:基础 URL 校验通过(绿色对勾),默认语言 ZH

3.3 关闭遥测

系统设置 → 遥测:DT 默认会定期向官方项目上报“匿名使用统计“。图 4 里那段 JSON 就是它最后一次自动提交的内容(system_id 系统标识、dt_version 版本、db_type/db_version 数据库信息)。

关闭遥测

图 4:遥测设置页:“启用遥测提交“已关闭;下方 JSON 是最后一次自动提交的内容(DT 5.2.0、PostgreSQL 18.6)

为什么关:一是原则问题,内网环境不想让“我们在跑一个 DT“这件事以任何形式外泄;二是内网本来就发不出去。这段 JSON 也顺带确认了两个事实:本环境是 DT 5.2.0,数据库是 PostgreSQL 18.6。

3.4 添加漏洞数据源

DT 的漏洞匹配 = SBOM 组件 × 启用的数据源。系统设置里相关页面分两组:漏洞来源(Vulnerability Sources)和 KEV Sources(已知被利用漏洞源)。

先建两个密钥(系统设置 → 密钥管理)。DT 调第三方 API 用“密钥“(名称 → 真实值)间接引用,避免每个配置页都填一遍真值:

  • vulncheck:到 vulncheck 官网注册并申请 API key(免费社区版就够,官方页面原话 “A free community token is sufficient”),在密钥管理里建一个名为 vulncheck 的密钥(图 5,真实值已在图中打码)。
  • ossindex:Sonatype(OSS Index 的维护方)免费注册账号,申请一个 PAT(Personal Access Token,个人访问令牌,让程序代表你调 API 的凭据,Sonatype 的以 sonatype_pat_ 开头),建名为 ossindex 的密钥(图 6,已打码)。

创建 vulncheck 密钥

图 5:密钥管理-创建密钥:名称 vulncheck,值为官网申请的 API key(图中已打码)

创建 ossindex 密钥

图 6:密钥管理-创建密钥:名称 ossindex,值为 Sonatype 的 PAT(sonatype_pat_ 开头,图中已打码)

启用 VulnCheck KEV 源(KEV Sources → VulnCheck KEV,图 7):打开 Enabled,API URL 保持默认 https://api.vulncheck.com,API Token 下拉选 vulncheck 密钥。页面官方说明:VulnCheck KEV 是社区维护的“已被真实利用“漏洞目录,比 CISA 官方 KEV 覆盖更多漏洞、记录更早,组件命中它则修复优先级最高。配完可以点 “Mirror now” 立即同步一批数据。

VulnCheck KEV 配置

图 7:KEV Sources 里的 VulnCheck KEV:已启用,API URL 与 Token(选密钥名)已配

启用 Sonatype OSS Index(漏洞来源 → Sonatype OSS Index,图 8):打开 Enabled(Alias Synchronization 默认开,同步组件别名信息,利于匹配),API URL 默认 https://ossindex.sonatype.org,Username 填 Sonatype 账号邮箱,API Token 下拉选 ossindex 密钥,可以先点 Test 验证连通再保存。

Sonatype OSS Index 配置

图 8:漏洞来源里的 Sonatype OSS Index:已启用,Username 为 Sonatype 账号邮箱,API Token 选 ossindex 密钥

为什么加这两个:DT 内置数据源已具备基础匹配能力,加源是为了扩大覆盖面。OSS Index 是 Sonatype 维护的免费社区漏洞库,数据量大;VulnCheck 补“真实被利用“维度。源越多召回率越高,但可能引入误报、分析变慢。本环境选“宁多勿漏“,两个都加;你也可以按需开关。

3.5 配置 Gitea SSO(OIDC)登录

接入方式与其它平台相同:只在 Gitea(IdP)登录一次,其它系统都问 Gitea“这人是谁“。配置分两侧:

Gitea 侧建 OAuth2 应用(图 9):Gitea → 组织(dev-sec-ops)→ 设置 → 应用 → 创建 OAuth2 应用程序:

  • 应用名称:DependencyTrack;
  • 重定向 URL:https://dependency-track.kali-team.internal/static/oidc-callback.html,DT 固定的回调页。用户在 Gitea 授权后,Gitea 会把浏览器送回这个地址完成登录闭环;
  • 机密客户端:勾选(confidential client,有密钥的后端 Web 应用,区别于跑在用户本地的脚本类应用)。

保存后 Gitea 生成 Client ID 和 Client Secret(图 9 已抹掉真实值;Client Secret 等同于密码,只进 DT 的 values/配置,不进文章和提交记录)。

Gitea OAuth2 应用

图 9:Gitea 组织的 OAuth2 应用:应用名 DependencyTrack,重定向 URL 指向 DT 的回调页,勾选机密客户端

DT 侧:上面的 DT_OIDC_* 环境变量就是 DT 侧的全部配置(issuer/client/claim/自动建用户/团队同步),装好即生效,界面上无需再填。

团队同步(图 10):系统设置 → 用户和权限 → OpenID Connect 组。本环境预建了 dev-sec-ops 团队(与 Gitea 组织同名)。用户登录时,DT 按令牌里的 groups 声明把人放进对应团队。团队是 DT 的权限单元:权限(如 API 密钥权限)授给团队,团队成员自动获得,权限管理从此按“团队“而不是“个人“来。

OIDC 组

图 10:OpenID Connect 组:预建了 dev-sec-ops 团队,用于按 groups 声明同步用户

登录流程(图 11–13):DT 登录页此时只剩一个 OpenID 按钮(图 11;密码登录在“更多选项“里)→ 点击跳 hub 授权 → 浏览器被送回 DT 回调页 → DT 自动创建用户、进入面板(图 13,右上角显示“已连接为 Kali-Team“)。首次登录后在 OpenID Connect 用户表里能看到自动创建的用户记录(图 12)。

OIDC 登录页

图 11:DT 登录页:OIDC 开启后主入口是 OpenID 按钮,密码登录收入“更多选项“

OIDC 用户

图 12:OpenID Connect 用户表:首次登录后自动创建 Kali-Team 用户(主题标识符 16,所属 3 个团队)

OIDC 登录后面板

图 13:OIDC 登录后进入面板(中文界面),右上角显示当前身份 Kali-Team

现状说明:本环境日常操作目前仍用 DT 的本地 admin 账号登录。Gitea SSO 链路已按上述配置完成并验证(图 11–13);SSO 不可用时,用本地 admin 账号操作即可,不影响流水线(流水线走 API Token,不走 SSO)。

3.6 给 CI 建 API Token(团队 API 密钥)

流水线要往 DT 里传 SBOM,需要机器身份:界面登录是给人用的,程序调 REST API 用 API token,不给它人的账号。

本环境用团队 API 密钥(图 14):

  1. 系统设置 → 用户和权限 → 团队:可以看到 Administrators(1 名成员,即 admin)和 Automation(0 名成员,专为 CI 建的“纯机器团队“,不挂真人)。
  2. 进入 Automation 团队页添加 API 密钥。密钥有一个 Public ID(公开标识);密钥本体(secret)只在创建那一刻显示一次,直接复制进 Gitea 仓库的 Secret DEPENDENCYTRACK_APIKEY。
  3. 给团队配最小权限:BOM_UPLOAD(允许上传 SBOM)+ VIEW_PORTFOLIO(允许查看面板)+PROJECT_CREATION_UPLOAD(允许项目的创建)。CI 只需要“投递清单 + 看结果“,不给管理权限。

Automation 团队与 API 密钥

图 14:团队页- Automation 团队:API 密钥已创建(图中可见 Public ID,密钥本体创建时一次性显示),权限仅 BOM_UPLOAD 与 VIEW_PORTFOLIO

页面有一句官方提示(原意):团队 API 密钥永不过期,且无法归属到具体使用者,人多时建议改用 service account(服务账号)。本环境 CI 只有一条流水线、一个密钥,团队密钥够用;如果以后多个自动化都来传,就迁到服务账号(能定位到“是谁在用“)。

4 使用:SBOM 生成与上传

4.1 创建项目

界面上:PORTFOLIO → 项目 → 新建项目(名称/版本/描述)。本例没手工建,由流水线 autoCreate 自动创建,效果等价于在界面建了名为 example、版本 main 的项目。私有项目的处理见“常见问题与坑“。

4.2 Go 项目生成 SBOM(CycloneDX)

工具选 cyclonedx-gomod:CycloneDX 官方针对 Go 生态的 SBOM 生成器,读 go.mod/go.sum 就能出清单。命令(项目根目录执行):

cyclonedx-gomod app \
  -json \
  -output bom.json \
  -packages -files -licenses -main \
  .

逐参数说:

  • app:子命令 = 生成“应用依赖“的 SBOM(该工具还有其它子命令,cyclonedx-gomod help 可查);
  • -json:输出 JSON 格式(CycloneDX 也支持 XML);
  • -output bom.json:写到文件(不写就打到终端);
  • -packages:包含模块里的全部包(不只被直接 import 的);
  • -files:包含文件级信息;
  • -licenses:附带各组件的许可证信息(从模块源码的 license 文件读);
  • -main:把主模块(example 项目自己)也作为组件收录(application 类型),SBOM 里就能看出“这份清单属于哪个应用“;
  • .:要分析的项目目录(go.mod 所在处)。

4.3 实测:example 项目的 SBOM

用与流水线完全相同的命令(任务容器镜像、Go 1.25.14、模块依赖走 Nexus goproxy)实际跑了一遍,结果:

  • 输出 bom.json 共 418 KiB(428,224 字节);
  • 16 个组件,与 go.mod 的 16 个 require 一一对应(1 个直接依赖 + 15 个间接依赖);
  • 内容节选(真实输出,缩写):
{
  "bomFormat": "CycloneDX",
  "specVersion": "1.6",
  "serialNumber": "urn:uuid:a17815c3-…",
  "metadata": {
    "component": {
      "type": "application",
      "name": "hub.kali-team.internal/dev-sec-ops/example",
      "version": "v0.0.0-20261016082839-9cae0e5",
      "purl": "pkg:golang/hub.kali-team.internal/dev-sec-ops/example@…?type=module"
    }
  },
  "components": [
    {
      "name": "github.com/gin-gonic/gin",
      "version": "v1.10.0",
      "type": "library",
      "purl": "pkg:golang/github.com/gin-gonic/[email protected]?goarch=amd64&goos=linux&type=module"
    }
    …(共 16 个)
  ]
}

两个值得注意的细节:

  • 主模块的版本是 Go 的伪版本(pseudo-version)v0.0.0-日期时间-提交号前缀:对没有正式 tag 的仓库,Go 用 git 信息自动生成版本号。从它就能看出这份 SBOM 生成时用的是哪个提交(9cae0e5 正是当时的代码提交)。
  • 运行时有条警告 no licenses detected:example 项目没有 LICENSE 文件,所以 -licenses 无内容可读(参数本身有效,换个带许可证的项目就会带上许可证信息)。

4.4 上传 SBOM 到 DT

两种方式:

  • 界面:项目页 → BOMs → 上传文件(试用、偶尔手工传一次,用这个);
  • REST API(CI 用这个):
curl -F "[email protected]" \
     -F "autoCreate=true" \
     -F "projectName=example" \
     -F "projectVersion=main" \
     -H "X-Api-Key: <dt-api-token>" \
     https://dependency-track.kali-team.internal/api/v1/bom
  • X-Api-Key 请求头认证(上面的团队 API 密钥);autoCreate=true 表示“项目不存在就现场建“(此时 projectName/projectVersion 生效);成功返回 200,响应体是这份 BOM 的唯一 ID(UUID)。
  • 流水线是机器,点不了按钮,API 就是“界面上传按钮“的程序形态,行为和界面一致。

4.5 DT 的分析机制:上传之后发生了什么

DT 收到 BOM 后:

  1. 入库:解析组件,按 PURL + 版本去重,挂到项目下(项目可以有多个 BOM 版本,对应不同代码版本);
  2. 匹配:拿每个组件去各启用的漏洞源比对(CycloneDX 的 purl 是主匹配键);
  3. 出报告:项目页生成漏洞清单:漏洞编号、严重级别、影响版本、修复版本、是否 KEV 等;
  4. 持续分析:DT 定期从各源镜像新数据,新漏洞落地后自动对存量组件重匹配,不用重传 SBOM。

所以“上传一次“= 登记了依赖快照,之后 DT 持续盯着。

4.6 漏洞报告怎么读

(按 DT 5.x 的界面设计讲解;字段含义以官方文档为准。)

  • 项目页顶部统计卡:项目漏洞数、有漏洞的组件数等;严重级别分布 Critical(严重)/ High(高危)/ Medium(中危)/ Low(低危)。
  • 单条漏洞怎么看:
    • 漏洞 ID:CVE-20xx-xxxx 这类公开编号,可拿去查详情;
    • 是否 KEV:真实世界已被利用 → 修复优先级最高,别排期,直接修;
    • 影响版本 / 修复版本:给了修复版本就直接升级依赖(Go 里 go get github.com/[email protected]),然后重跑流水线生成新 SBOM 再传,DT 会自动对比新旧版本,修掉的漏洞从清单里消掉;
    • 组件 PURL:对照 go.mod 确认是哪个依赖、直接还是间接。
  • 面板(Dashboard,图 13):跨项目聚合:“全部项目总体安全水位“看这里;单个项目的细节看项目页。

4.7 按语言选 SBOM 生成工具

上文是 Go 的完整流程(cyclonedx-gomod)。团队若有 Node.js / Python 项目,选工具逻辑不变:每种语言选一个主流的 CycloneDX 生成器,产出同样格式的 bom.json,按上文的上传方式原样照用。常用三语言的速查表:

语言推荐工具安装生成
Gocyclonedx-gomodgo install(模块经 Nexus goproxy)cyclonedx-gomod app -json -output bom.json -packages -files -licenses -main .(参数说明见上文)
Node.js@cyclonedx/cyclonedx-npmnpm install -g @cyclonedx/cyclonedx-npmcyclonedx-npm --output-file bom.json
Pythoncyclonedx-bompip install cyclonedx-bomcyclonedx-py --output bom.json

其他语言与构建工具(Java、.NET 等)的完整工具清单,以 CycloneDX 官方 Tool Center 为准,上表只是最常用的速查。

一句提醒:安装命令(npm / pip)要求对应包源可达(包源 = 安装第三方库时下载库文件的服务器,相当于 Go 的 GOPROXY);内网开发机按本环境的源配置执行,或在有外网的机器上先装好再使用。

4.8 UI 里看结果点哪里

上一节讲了“漏洞报告怎么读“,这一节只讲“点哪里“:项目详情页的四个主要 tab:

  • Vulnerabilities(漏洞):项目漏洞清单,按严重级别分类;
  • Components(组件):项目包含的组件列表(对应 SBOM 里的 components),从这里看“哪个组件带漏洞“;
  • Licenses(许可证):各组件的许可证信息,合规视角,与漏洞互补;
  • BOMs(SBOM):上传历史:每次上传的时间、格式(CycloneDX)、版本、组件数都在这里;“界面上传“入口也在这一页。

一个项目可以有多个 BOM 版本(对应不同代码版本,4.5 的“入库“按 PURL + 版本去重),BOMs 页就是这些版本的列表。

5 CI 联动:dependency-track.yaml 逐段讲

两条流水线分工:SonarQube 那条看代码质量,这条看依赖安全,同一仓库、互不干扰。

5.1 自托管 action

  • actions/cyclonedx-gomod-generate-sbom@v2:go run github.com/CycloneDX/cyclonedx-gomod/cmd/cyclonedx-gomod@<version> <args>,依赖走 GOPROXY(Nexus),带 -buildvcs=false 绕开 Go 1.25 的 VCS 戳记问题;
  • actions/upload-sbom@v3:curl -F multipart POST /api/v1/bom,非 2xx 响应按失败处理。

5.2 流水线全文(已入库 example 仓库,commit 9cae0e5)

on:
  push:
    tags:
      - "v*"
  pull_request:
      types: [opened, synchronize, reopened]
  repository_dispatch:  # 通过 Webhook 触发
  workflow_dispatch:   # 支持手动立即触发
# 说明:
# - 旧版引用的旧环境自托管 action(gh-gomod-generate-sbom / gh-upload-sbom)已随旧环境失效,
#   现改为 Gitea actions 组织自托管的 cyclonedx-gomod-generate-sbom / upload-sbom(composite 实现)。
# - cyclonedx-gomod 的模块依赖走 Nexus goproxy(任务容器自带 Go,无需 setup-go);
#   SBOM 经 DT REST API(POST /api/v1/bom,multipart)上传。
name: DependencyTrack Workflow
jobs:
  dependency-track:
    runs-on: ubuntu-host
    env:
      GOPROXY: "https://nexus.kali-team.internal/repository/goproxy/"  # Go 模块走 Nexus 代理
      GOSUMDB: "sum.golang.org https://nexus.kali-team.internal/repository/go-sumdb/"  # sumdb 校验走 Nexus go-sumdb 代理,保持在线校验不关闭(go.sum 本地哈希校验始终生效)
    steps:
      - name: Init导入内网CA证书
        run: |
          echo -n | openssl s_client -showcerts -connect hub.kali-team.internal:443 2>/dev/null | sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' >> hub.kali-team.internal.crt
          sudo cp hub.kali-team.internal.crt /usr/local/share/ca-certificates/
          sudo update-ca-certificates
      - name: Checkout code
        uses: https://hub.kali-team.internal/actions/checkout@v4
        env:
          GIT_SSL_NO_VERIFY: true
        with:
          submodules: true
          fetch-depth: 0
          token: ${{ secrets.TOKEN }}
      - name: Verify Certificate 信任dev-sec-ops证书
        run: |
          sudo cp kali-team-ca.crt /usr/local/share/ca-certificates/
          sudo update-ca-certificates
          sudo mkdir -p /etc/docker/certs.d/mirror.kali-team.internal
          sudo cp kali-team-ca.crt /etc/docker/certs.d/mirror.kali-team.internal/ca.crt
      - name: 准备 Go 模块依赖
        run: |
          go version
          go mod download
      - name: 生成 CycloneDX SBOM
        uses: https://hub.kali-team.internal/actions/cyclonedx-gomod-generate-sbom@v2
        with:
          version: "v1.10.0"  # cyclonedx-gomod 的 Go 模块版本(经 Nexus goproxy 下载编译)
          args: "app -json -output bom.json -packages -files -licenses -main ."  # 生成 SBOM 文件,输出为 bom.json
      - name: 上传 SBOM 到 Dependency-Track
        uses: https://hub.kali-team.internal/actions/upload-sbom@v3
        with:
          serverHostname: dependency-track.kali-team.internal  # DependencyTrack 的域名
          port: "443"  # 端口
          protocol: https  # 协议
          apiKey: ${{ secrets.DEPENDENCYTRACK_APIKEY }}  # DT 的 API 密钥(只存 repo Secret,文章里用占位符)
          projectName: example  # DT 上创建的项目名称(autoCreate 时)
          projectVersion: main  # DT 上创建的项目版本
          bomFilename: bom.json  # 上一步生成的 bom.json 文件
          autoCreate: "true"  # 项目不存在时自动创建。注意:自动创建的项目默认所有人可见;
                              # 若要私有项目:在 DT 上手动建项目并加入 Automation 团队,
                              # 然后这里 autoCreate 设 false,并用 project 参数传项目 UUID

逐段讲:

  1. on 触发条件:推 v* tag(每次发版自动做“依赖安全验收“)、PR(合并前看一眼)、repository_dispatch(Webhook 触发,比如漏洞源大更新后批量重刷)、workflow_dispatch(Gitea 页面手动跑)。
  2. job 级 env:GOPROXY 指向 Nexus goproxy(Go 模块全走内网,与 Dockerfile 一致);GOSUMDB 指向 Nexus go-sumdb 代理(两字段写法,sumdb 查询走内网、在线校验保持开启;go.sum 的本地哈希校验始终生效)。
  3. Init:openssl s_client 从 hub 拉证书链装进系统 CA 库,后续访问 nexus/DT 的 https 才能通过证书校验。
  4. Checkout:自托管 checkout action(完整 URL 引用 @v4)。
  5. Verify Certificate:安装仓库自带的 kali-team-ca.crt(step 中间 CA + 根 CA),覆盖所有内网平台的证书。
  6. 准备 Go 模块依赖:go mod download 下载 example 自己的依赖(顺带校验 go.sum)。
  7. 生成 CycloneDX SBOM:上面那节的自托管 action,参数即上面的生成命令,产出 bom.json。
  8. 上传 SBOM 到 Dependency-Track:上面那节的自托管 action;apiKey 来自 repo Secret DEPENDENCYTRACK_APIKEY(Automation 团队密钥);autoCreate=true + projectName=example + projectVersion=main。

5.3 Secret 清单与域名解析

Secret(只存 Gitea 仓库设置,文/码中一律占位):

Secret内容谁签发
TOKENGitea 访问令牌(checkout 用)Gitea
DEPENDENCYTRACK_APIKEYDT Automation 团队 API 密钥DT

任务容器的域名解析(本环境实际踩到的坑):流水线任务容器不继承宿主机的 /etc/hosts,它解析内网域名靠 runner 配置的 container.options:

--add-host=hub.kali-team.internal:10.111.13.105
--add-host=mirror.kali-team.internal:10.111.13.105
--add-host=nexus.kali-team.internal:10.111.13.105
--add-host=sonarqube.kali-team.internal:10.111.13.105
--add-host=rancher.kali-team.internal:10.111.13.99
--add-host=ca.kali-team.internal:10.111.13.99
# DT 上线后追加:
--add-host=dependency-track.kali-team.internal:<IP>

宿主机 /etc/hosts 和 runner --add-host 两层都要有,流水线才能访问到 DT。

6 效果

流水线跑起来之后,example 项目在 DT 里的现状如下。四张图是项目页最常用的四个 tab:概览、组件、漏洞审计、利用预测。

example 项目概览

图 15:example 项目概览页:43 条漏洞(Critical 10 / High 15 / Medium 17 / Low 1),风险评分 227;BOM 导入于 32 天前、最近一次分析在 2 小时前。漏洞源同步新数据后 DT 自动对存量组件重新匹配,无需重传 SBOM

example 项目组件列表

图 16:example 项目组件 tab:共 430 个组件:除 16 个模块依赖外,-files 参数还把项目源码文件作组件带了进来;列表给出每个组件的版本、许可证、风险评分与漏洞数

example 项目漏洞审计

图 17:example 项目漏洞审计 tab:每条漏洞列出受影响组件与版本、CVE 编号、严重程度、KEV 标记和命中数据源(分析器列,截图中均为 OSS Index)

example 项目利用预测

图 18:example 项目利用预测 tab:每条漏洞的 CVSSv3 分值与 EPSS(Exploit Prediction Scoring System)分值、百分位数;EPSS 估计漏洞近期在真实攻击中被利用的概率,分值越高越值得优先修

日常查看顺序:概览看严重级别分布掌握整体情况,组件里定位漏洞在哪个组件,漏洞审计和利用预测合起来决定修复优先级。

7 常见问题与坑

  1. master key 管理。 必须固定在 values(本环境 provider: database + mode: config),和数据库密码同一安全等级保存;丢了,库里的加密数据(API token 等)全部无法恢复。本文及一切公开场合只用占位符 <master-key>。
  2. autoCreate 建出的项目是公开的。 流水线自动创建的项目默认所有人可见。要私有项目:界面手工建项目(设为私有)→ 把项目加入 Automation 团队(授上传权限)→ 流水线 autoCreate 改 false,用 project 参数传项目 UUID。
  3. 漏洞源的第三方密钥。 vulncheck 免费社区 token 即可(官方 UI 原文 “A free community token is sufficient”);ossindex 必须申请 Sonatype 账号的 PAT(免费)。密钥只进 DT 的密钥管理(CI 侧只进 Gitea Secret),文章/提交/聊天里一律占位符,本环境记录截图中的密钥值也已打码。

小结

这一篇给内网 DevSecOps 体系补上了依赖安全一环:流水线生成 CycloneDX SBOM(go run 走 Nexus goproxy,零外网),推给 DT,DT 持续匹配各漏洞源,依赖的已知漏洞从此在面板上可见、可排序、可追踪。

  • 搭建:复用现有设施:middleware 共享 PostgreSQL(kubectl 临时 pod 建库)、local-path PVC、Traefik ingress;values 的要点是数据源、master key、OIDC、ingress;
  • 初始配置三件事:关遥测(数据不出内网)、加漏洞源(vulncheck KEV + ossindex,扩大召回)、建 API Token(机器账号、最小权限 BOM_UPLOAD + VIEW_PORTFOLIO);
  • OIDC 登录:Gitea 当 IdP,DT 接入统一登录,团队按 groups 声明自动同步;
  • CI 联动:两个 action 用 composite 重做(go run + curl);域名解析是两层问题(宿主机 /etc/hosts + runner --add-host)。

下一步可选:DT 策略(Policies and Conditions,例如“命中 KEV 即违规“)、webhook 通知(漏洞更新推 Gitea/IM)、portfolio 访问控制,以及把更多项目类型接进来(CycloneDX 生态里各语言都有 SBOM 工具)。

参考