dependency-track

Dependency-Track 技能

全面介绍 Dependency-Track 的实现、部署和运维指南。Dependency-Track 是一个智能软件成分分析（SCA）平台，通过 SBOM 管理识别并降低软件供应链风险。

当前版本：

• Helm Chart：0.40.0
• 应用版本：4.13.6
• Helm 仓库：https://dependencytrack.github.io/helm-charts

概览

Dependency-Track 是一个 API 优先的平台，可以：

• 使用和生成 CycloneDX SBOM 和 VEX 文档
• 监控整个产品组合中的组件，识别已知漏洞
• 集成 NVD、GitHub Advisories、OSS Index、Snyk、Trivy、OSV 和 VulnDB
• 提供安全、许可证和运维合规的策略执行功能
• 支持 OAuth 2.0、OIDC、LDAP 和 Active Directory 身份验证
• 支持 EPSS（漏洞利用预测评分系统），用于风险优先级排序
• 识别 API 和外部服务组件

快速参考

资源	路径
部署模板	references/deployment/
CI/CD 集成	references/cicd/
API 示例	references/api/
策略模板	references/policies/
故障排除	references/troubleshooting.md

---

1. 部署选项

Docker Compose（生产环境推荐）

# Download official docker-compose
curl -LO https://dependencytrack.org/docker-compose.yml

# Start services
docker compose up -d

# Access UI at http://localhost:8080
# Default credentials: admin / admin

最低要求：

• API 服务：4.5GB RAM、2 个 CPU 核心
• 前端：512MB RAM、1 个 CPU 核心

推荐配置：

• API 服务：16GB RAM、4 个 CPU 核心
• 前端：1GB RAM、2 个 CPU 核心

使用 Helm 部署到 Kubernetes

# Add Helm repository
helm repo add dependency-track https://dependencytrack.github.io/helm-charts
helm repo update

# View available charts
helm search repo dependency-track

# Install with custom values
helm install dtrack dependency-track/dependency-track \
    --namespace dtrack \
    --create-namespace \
    -f values-production.yaml

# Upgrade existing installation
helm upgrade dtrack dependency-track/dependency-track \
    --namespace dtrack \
    -f values-production.yaml

可用 Chart：

Chart	描述	状态
dependency-track/dependency-track	单体部署（v4.x）	可用于生产环境
dependency-track/hyades	微服务部署（v5.x）	孵化中（尚未正式发布）

完整的清单和 Helm values 请参阅 references/deployment/。

ArgoCD GitOps 部署（AKS）

使用 ArgoCD 和多源 ApplicationSet 部署企业级 Kubernetes 环境：

目录结构：

infra-team/
  applicationset/
    dependency-track.yaml       # ArgoCD ApplicationSet definition
argo-cd-helm-values/
  kube-addons/
    dependency-track/
      azure-ad-setup.sh         # Azure AD App Registration script
      example-app-dev/
        values.yaml             # Environment-specific Helm values
        secretproviderclass.yaml # Azure Key Vault CSI integration

ApplicationSet 示例（多源）：

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: dependency-track
  namespace: argocd
spec:
  generators:
    - list:
        elements:
          - cluster: example-app-dev
            url: https://aks-cluster-url:443
            project: kube-addons
            branch: main
            environment: development
            urlSuffix: ".dev"
  template:
    metadata:
      name: "{{cluster}}-dependency-track"
      finalizers:
        - resources-finalizer.argocd.argoproj.io
    spec:
      project: "{{project}}"
      sources:
        # Source 1: Helm chart from official repository
        - chart: dependency-track
          repoURL: https://dependencytrack.github.io/helm-charts
          targetRevision: "0.40.0"
          helm:
            releaseName: dependency-track
            valueFiles:
              - $values/argo-cd-helm-values/kube-addons/dependency-track/{{cluster}}/values.yaml
        # Source 2: Values repository reference
        - repoURL: https://your-git-repo.git
          targetRevision: "{{branch}}"
          ref: values
        # Source 3: Additional manifests (SecretProviderClass)
        - repoURL: https://your-git-repo.git
          targetRevision: "{{branch}}"
          path: argo-cd-helm-values/kube-addons/dependency-track/{{cluster}}
          directory:
            exclude: values.yaml
      destination:
        server: "{{url}}"
        namespace: dependency-track
      syncPolicy:
        automated:
          prune: true
          selfHeal: true
        syncOptions:
          - ServerSideApply=true
          - CreateNamespace=true

Azure Key Vault CSI Driver（SecretProviderClass）：

apiVersion: secrets-store.csi.x-k8s.io/v1
kind: SecretProviderClass
metadata:
  name: dependency-track-secrets-kv
  namespace: dependency-track
spec:
  provider: azure
  parameters:
    usePodIdentity: "false"
    useVMManagedIdentity: "true"
    userAssignedIdentityID: "<managed-identity-client-id>"
    keyvaultName: "<key-vault-name>"
    tenantId: "<tenant-id>"
    objects: |
      array:
        - |
          objectName: "dtrack-oidc-client-id"
          objectType: "secret"
          objectAlias: "oidc-client-id"
        - |
          objectName: "dtrack-oidc-client-secret"
          objectType: "secret"
          objectAlias: "oidc-client-secret"
  secretObjects:
    - secretName: dependency-track-secrets
      type: Opaque
      data:
        - objectName: oidc-client-id
          key: oidc-client-id
        - objectName: oidc-client-secret
          key: oidc-client-secret

AKS Spot 实例容忍度（成本优化）：

apiServer:
  tolerations:
    - key: kubernetes.azure.com/scalesetpriority
      operator: Equal
      value: spot
      effect: NoSchedule
  affinity:
    nodeAffinity:
      preferredDuringSchedulingIgnoredDuringExecution:
        - weight: 100
          preference:
            matchExpressions:
              - key: kubernetes.azure.com/scalesetpriority
                operator: In
                values:
                  - spot

ArgoCD 的关键 ignoreDifferences 配置：

ignoreDifferences:
  # StatefulSet VolumeClaimTemplates (ServerSideApply drift)
  - group: apps
    kind: StatefulSet
    jqPathExpressions:
      - .spec.volumeClaimTemplates[]?.apiVersion
      - .spec.volumeClaimTemplates[]?.kind
      - .spec.volumeClaimTemplates[]?.status
  # PVC dynamic fields
  - group: ""
    kind: PersistentVolumeClaim
    jsonPointers:
      - /status
      - /spec/volumeName
  # Azure Key Vault synced secrets
  - group: ""
    kind: Secret
    name: dependency-track-secrets
    jsonPointers:
      - /data

完整的 ApplicationSet 和 values 示例请参阅 references/deployment/argocd/。

Hyades（新一代架构）

Hyades 是 Dependency-Track v5 的孵化项目，将单体 API 服务拆分为独立且可扩展的微服务。

组件：

• hyades-apiserver - 核心 API 服务
• hyades-frontend - Web UI
• hyades-notification-publisher - 通知处理
• hyades-repository-meta-analyzer - 仓库元数据分析
• hyades-vulnerability-analyzer - 漏洞扫描

要求：

• 外部 PostgreSQL 数据库
• Apache Kafka 集群
• Kubernetes 1.19+

# Install Hyades (NOT PRODUCTION READY)
helm install hyades dependency-track/hyades \
    --namespace dtrack \
    --create-namespace \
    --set common.database.jdbcUrl="jdbc:postgresql://postgres:5432/dtrack" \
    --set common.database.username="dtrack" \
    --set common.database.password="secret" \
    --set common.kafka.bootstrapServers="kafka:9092"

警告： Hyades 尚未正式发布。可能会在未通知的情况下发生破坏性变更。仅用于测试环境。正式发布路线图：https://github.com/DependencyTrack/hyades/issues/860

---

2. 初始配置

首次设置

1. 等待初始化完成（10-30 分钟以上）：

   • 创建默认用户、团队和权限
   • 同步 NVD、GitHub Advisories（请勿中断）
   • 查看进度：docker logs -f dependency-track-apiserver

2. 首次登录后立即更改默认密码

3. 在 Administration > Analyzers 中启用分析器：

   • Internal Analyzer（内置）
   • OSS Index（需要从 ossindex.sonatype.org 获取 API 令牌）
   • Snyk（可选，需要令牌）
   • Trivy（可选）

数据库配置（生产环境）

# docker-compose override for PostgreSQL
services:
  apiserver:
    environment:
      ALPINE_DATABASE_MODE: external
      ALPINE_DATABASE_URL: jdbc:postgresql://postgres:5432/dtrack
      ALPINE_DATABASE_DRIVER: org.postgresql.Driver
      ALPINE_DATABASE_USERNAME: dtrack
      ALPINE_DATABASE_PASSWORD: ${DB_PASSWORD}

LDAP/Active Directory

# Active Directory configuration
ALPINE_LDAP_ENABLED=true
ALPINE_LDAP_SERVER_URL=ldap://ldap.example.com:3268
ALPINE_LDAP_BASEDN=dc=example,dc=com
ALPINE_LDAP_SECURITY_AUTH=simple
ALPINE_LDAP_AUTH_USERNAME_FORMAT=%[email protected]
ALPINE_LDAP_ATTRIBUTE_NAME=userPrincipalName
ALPINE_LDAP_ATTRIBUTE_MAIL=mail
ALPINE_LDAP_GROUPS_FILTER=(&(objectClass=group)(objectCategory=Group))
ALPINE_LDAP_USER_GROUPS_FILTER=(&(objectClass=group)(member:1.2.840.113556.1.4.1941:={USER_DN}))

OpenID Connect（Azure AD、Okta、Keycloak）

ALPINE_OIDC_ENABLED=true
ALPINE_OIDC_ISSUER=https://login.microsoftonline.com/{tenant}/v2.0
ALPINE_OIDC_CLIENT_ID=your-client-id
ALPINE_OIDC_USERNAME_CLAIM=preferred_username
ALPINE_OIDC_TEAMS_CLAIM=groups
ALPINE_OIDC_USER_PROVISIONING=true
ALPINE_OIDC_TEAM_SYNCHRONIZATION=true

Azure AD OIDC 群组集成（详细指南）

Dependency-Track 中的 OIDC 组工作方式

1. 组声明流程：

   • 用户通过 Azure AD 进行身份验证
   • Azure AD 返回包含 groups 声明（组对象 ID 数组）的 ID 令牌
   • Dependency-Track 读取 groups 声明（通过 ALPINE_OIDC_TEAMS_CLAIM 配置）
   • 通过 OpenID Connect Groups 映射将组关联到团队

2. 重要行为：

   • 只有该组中的用户完成身份验证后，组才会显示在 Administration > OpenID Connect Groups 中
   • 进行组映射前必须先创建团队（如果 ALPINE_OIDC_TEAM_SYNCHRONIZATION=true，则会自动创建）
   • 使用组对象 ID（UUID），而非显示名称

方法 1：基于 API 的设置（推荐）

使用 REST API 创建团队、OIDC 组和映射：

# Set environment variables
export DTRACK_URL="https://dtrack.example.com"
export DTRACK_API_KEY="your-api-key"

# Azure AD Group Object ID
AZURE_GROUP_ID="<AAD_GROUP_ID_ADMIN>"

# 1. Create a Team (if doesn't exist)
curl -X PUT "${DTRACK_URL}/api/v1/team" \
  -H "X-Api-Key: ${DTRACK_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"name": "Administrators"}'

# 2. Get the Team UUID
TEAM_UUID=$(curl -s -H "X-Api-Key: ${DTRACK_API_KEY}" \
  "${DTRACK_URL}/api/v1/team" | jq -r '.[] | select(.name=="Administrators") | .uuid')

# 3. Create OIDC Group (required before mapping)
# NOTE: Use Azure AD Group Object ID as both uuid and name
curl -X PUT "${DTRACK_URL}/api/v1/oidc/group" \
  -H "X-Api-Key: ${DTRACK_API_KEY}" \
  -H "Content-Type: application/json" \
  -d "{\"uuid\": \"${AZURE_GROUP_ID}\", \"name\": \"${AZURE_GROUP_ID}\"}"

# 4. Get the created OIDC Group UUID
OIDC_GROUP_UUID=$(curl -s -H "X-Api-Key: ${DTRACK_API_KEY}" \
  "${DTRACK_URL}/api/v1/oidc/group" | jq -r ".[] | select(.name==\"${AZURE_GROUP_ID}\") | .uuid")

# 5. Create OIDC Group-to-Team mapping
# IMPORTANT: Use UUID strings directly, NOT objects
curl -X PUT "${DTRACK_URL}/api/v1/oidc/mapping" \
  -H "X-Api-Key: ${DTRACK_API_KEY}" \
  -H "Content-Type: application/json" \
  -d "{\"team\": \"${TEAM_UUID}\", \"group\": \"${OIDC_GROUP_UUID}\"}"

# 6. Assign permissions to Team
curl -X POST "${DTRACK_URL}/api/v1/permission/BOM_UPLOAD/team/${TEAM_UUID}" \
  -H "X-Api-Key: ${DTRACK_API_KEY}"

IMPORTANT： /api/v1/oidc/mapping 端点需要 UUID 字符串，而不是对象。 使用 {"team": {"uuid": "..."}, "group": {"uuid": "..."}} 将返回 HTTP 400。

验证 OIDC 组映射

使用以下命令验证 OIDC 组是否已正确映射到团队：

# Set environment variables
export DTRACK_URL="https://dtrack.example.com"
export DTRACK_API_KEY="your-api-key"

# List all teams with their OIDC group mappings
/usr/bin/curl -s "${DTRACK_URL}/api/v1/team" \
  -H "X-Api-Key: ${DTRACK_API_KEY}" | \
  /usr/bin/jq '[.[] | select(.mappedOidcGroups | length > 0) | {
    team: .name,
    oidcGroups: [.mappedOidcGroups[] | .group.name]
  }]'

# List all OIDC groups registered in D-Track
/usr/bin/curl -s "${DTRACK_URL}/api/v1/oidc/group" \
  -H "X-Api-Key: ${DTRACK_API_KEY}" | \
  /usr/bin/jq '.[] | {uuid: .uuid, name: .name}'

# Check specific team's OIDC mappings
TEAM_NAME="Administrators"
/usr/bin/curl -s "${DTRACK_URL}/api/v1/team" \
  -H "X-Api-Key: ${DTRACK_API_KEY}" | \
  /usr/bin/jq --arg team "$TEAM_NAME" '.[] | select(.name==$team) | {
    name: .name,
    uuid: .uuid,
    oidcGroups: [.mappedOidcGroups[]? | {name: .group.name, uuid: .group.uuid}]
  }'

示例输出（example-app-dev 集群）：

[
  {"team": "Administrators", "oidcGroups": ["<AAD_GROUP_ID_ADMIN>"]},
  {"team": "Auditors", "oidcGroups": ["<AAD_GROUP_ID_AUDITOR>"]},
  {"team": "Developers", "oidcGroups": ["<AAD_GROUP_ID_DEVELOPER>"]},
  {"team": "Moderators", "oidcGroups": ["<AAD_GROUP_ID_MODERATOR>"]},
  {"team": "ReadOnly", "oidcGroups": ["<AAD_GROUP_ID_READONLY>"]}
]

注意： 使用完整路径（/usr/bin/curl、/usr/bin/jq），以避免自动化环境中的 shell 别名问题。

方法 2：在 UI 中手动配置

1. 创建团队：

   • 前往 Administration > Access Management > Teams
   • 创建团队：Administrators、Moderators、Auditors、Developers
   • 为每个团队分配权限

2. 映射组：

   • 前往 Administration > Access Management > OpenID Connect Groups
   • 点击“Create Group”
   • 输入 Azure AD 组对象 ID（例如 <AAD_GROUP_ID_ADMIN>）
   • 选择要映射到的团队
   • 保存

获取 Azure AD 组对象 ID

# List all Azure AD groups with DependencyTrack in name
az ad group list --filter "startswith(displayName, 'G-Usuarios-DependencyTrack')" \
  --query "[].{name:displayName, id:id}" -o table

# Get specific group Object ID
az ad group show --group "G-Usuarios-DependencyTrack-Admin" --query id -o tsv

验证 ID 令牌中的组声明

1. 解码 JWT 令牌（使用 jwt.io）：

   • 登录 Dependency-Track
   • 捕获发往 /api/v1/oidc/callback 的网络请求
   • 解码 id_token，确认 groups 声明包含预期的 UUID

2. Azure AD 令牌配置检查清单：

   • App Registration 中的 groupMembershipClaims: SecurityGroup
   • Optional Claims 中包含 ID Token 的 groups
   • API Permissions：GroupMember.Read.All（delegated）
   • 已授予管理员许可

环境变量参考

变量	描述	示例
ALPINE_OIDC_ENABLED	启用 OIDC	true
ALPINE_OIDC_ISSUER	Azure AD 颁发者 URL	https://login.microsoftonline.com/{tenant}/v2.0
ALPINE_OIDC_CLIENT_ID	App Registration 客户端 ID	来自 Key Vault
ALPINE_OIDC_CLIENT_SECRET	App Registration 密钥	来自 Key Vault
ALPINE_OIDC_USERNAME_CLAIM	用户名对应的声明	preferred_username
ALPINE_OIDC_TEAMS_CLAIM	组对应的声明	groups
ALPINE_OIDC_USER_PROVISIONING	自动创建用户	true
ALPINE_OIDC_TEAM_SYNCHRONIZATION	自动同步团队成员关系	true

---

3. CI/CD 集成

工作流：BOM 上传流水线

┌─────────────┐     ┌─────────────┐     ┌──────────────────┐
│   Build     │────▶│ Generate    │────▶│    Upload to     │
│   Project   │     │ CycloneDX   │     │ Dependency-Track │
└─────────────┘     │    SBOM     │     └──────────────────┘
                    └─────────────┘              │
                                                 ▼
                    ┌─────────────┐     ┌──────────────────┐
                    │   Break     │◀────│    Evaluate      │
                    │   Build?    │     │    Policies      │
                    └─────────────┘     └──────────────────┘

Jenkins 流水线

pipeline {
    agent any

    environment {
        DTRACK_URL = 'https://dtrack.example.com'
        DTRACK_API_KEY = credentials('dependency-track-api-key')
    }

    stages {
        stage('Build') {
            steps {
                sh 'mvn clean package'
            }
        }

        stage('Generate SBOM') {
            steps {
                sh 'mvn org.cyclonedx:cyclonedx-maven-plugin:makeAggregateBom'
            }
        }

        stage('Upload SBOM') {
            steps {
                dependencyTrackPublisher(
                    artifact: 'target/bom.xml',
                    projectId: env.PROJECT_UUID,
                    synchronous: true,
                    failedTotalCritical: 0,
                    failedTotalHigh: 5
                )
            }
        }
    }
}

GitHub Actions

name: SBOM Security Scan

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  sbom-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Generate SBOM
        uses: CycloneDX/gh-node-module-generatebom@v1
        with:
          output: ./bom.json

      - name: Upload to Dependency-Track
        uses: DependencyTrack/gh-upload-sbom@v3
        with:
          serverHostname: ${{ secrets.DTRACK_URL }}
          apiKey: ${{ secrets.DTRACK_API_KEY }}
          projectName: ${{ github.repository }}
          projectVersion: ${{ github.ref_name }}
          bomFilename: ./bom.json
          autoCreate: true

官方 GitHub Action 选项（DependencyTrack/gh-upload-sbom@v3）：

参数	必填	默认值	描述
serverHostname	是	-	Dependency-Track 服务 URL
apiKey	是	-	具有 BOM_UPLOAD 权限的 API 密钥
projectName	是	-	项目名称
projectVersion	是	-	项目版本
bomFilename	是	-	CycloneDX SBOM 文件路径
autoCreate	否	false	项目不存在时自动创建
parentName	否	-	父项目名称
parentVersion	否	-	父项目版本
projectUuid	否	-	使用 UUID，而非名称/版本

GitLab CI

stages:
  - build
  - security

generate-sbom:
  stage: build
  image: cyclonedx/cyclonedx-cli
  script:
    - cyclonedx-py -r requirements.txt -o bom.json
  artifacts:
    paths:
      - bom.json

upload-sbom:
  stage: security
  image: curlimages/curl
  script:
    - |
      curl -X PUT "${DTRACK_URL}/api/v1/bom" \
        -H "X-Api-Key: ${DTRACK_API_KEY}" \
        -H "Content-Type: application/json" \
        -d @- << EOF
      {
        "projectName": "${CI_PROJECT_NAME}",
        "projectVersion": "${CI_COMMIT_REF_NAME}",
        "autoCreate": true,
        "bom": "$(base64 -w0 bom.json)"
      }
      EOF

Azure DevOps 流水线

trigger:
  - main

pool:
  vmImage: 'ubuntu-latest'

variables:
  - group: dependency-track-credentials

steps:
  - task: Maven@4
    inputs:
      mavenPomFile: 'pom.xml'
      goals: 'package org.cyclonedx:cyclonedx-maven-plugin:makeAggregateBom'

  - task: Bash@3
    displayName: 'Upload SBOM to Dependency-Track'
    inputs:
      targetType: 'inline'
      script: |
        BOM_CONTENT=$(base64 -w0 target/bom.xml)
        curl -X PUT "$(DTRACK_URL)/api/v1/bom" \
          -H "X-Api-Key: $(DTRACK_API_KEY)" \
          -H "Content-Type: application/json" \
          -d "{\"projectName\":\"$(Build.Repository.Name)\",\"projectVersion\":\"$(Build.SourceBranchName)\",\"autoCreate\":true,\"bom\":\"${BOM_CONTENT}\"}"

---

4. REST API 用法

身份验证

在 Administration > Access Management > Teams > [Team] > API Keys 中生成 API 密钥。

# All API calls require the X-Api-Key header
curl -H "X-Api-Key: YOUR_API_KEY" \
     https://dtrack.example.com/api/v1/project

OpenAPI 规范

访问：

• JSON：http://localhost:8081/api/openapi.json
• YAML：http://localhost:8081/api/openapi.yaml

注意： 使用端口 8081（API 服务），而不是 8080（前端）。

常见 API 操作

# List all projects
curl -s -H "X-Api-Key: ${API_KEY}" \
     "${DTRACK_URL}/api/v1/project" | jq

# Get project by name and version
curl -s -H "X-Api-Key: ${API_KEY}" \
     "${DTRACK_URL}/api/v1/project/lookup?name=myapp&version=1.0.0" | jq

# Upload SBOM (Base64 encoded)
curl -X PUT "${DTRACK_URL}/api/v1/bom" \
     -H "X-Api-Key: ${API_KEY}" \
     -H "Content-Type: application/json" \
     -d "{
       \"projectName\": \"my-application\",
       \"projectVersion\": \"1.0.0\",
       \"autoCreate\": true,
       \"bom\": \"$(base64 -w0 bom.json)\"
     }"

# Upload SBOM (multipart - no encoding needed)
curl -X POST "${DTRACK_URL}/api/v1/bom" \
     -H "X-Api-Key: ${API_KEY}" \
     -F "projectName=my-application" \
     -F "projectVersion=1.0.0" \
     -F "autoCreate=true" \
     -F "[email protected]"

# Get vulnerabilities for a project
curl -s -H "X-Api-Key: ${API_KEY}" \
     "${DTRACK_URL}/api/v1/vulnerability/project/${PROJECT_UUID}" | jq

# Get policy violations
curl -s -H "X-Api-Key: ${API_KEY}" \
     "${DTRACK_URL}/api/v1/violation/project/${PROJECT_UUID}" | jq

# Get component dependencies
curl -s -H "X-Api-Key: ${API_KEY}" \
     "${DTRACK_URL}/api/v1/component/project/${PROJECT_UUID}" | jq

# Create project
curl -X PUT "${DTRACK_URL}/api/v1/project" \
     -H "X-Api-Key: ${API_KEY}" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "new-project",
       "version": "1.0.0",
       "description": "Project description",
       "tags": [{"name": "production"}]
     }'

---

5. 策略配置

策略类型

类型	用途	条件示例
许可证	控制允许或禁止的许可证	允许 Apache-2.0，禁止 GPL-3.0
安全	漏洞严重性阈值	不允许严重级别，最多 5 个高危级别
运维	组件允许列表/拒绝列表	禁止使用低于 2.17.0 的 log4j

通过 API 创建策略

# Create a security policy
curl -X PUT "${DTRACK_URL}/api/v1/policy" \
     -H "X-Api-Key: ${API_KEY}" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "No Critical Vulnerabilities",
       "operator": "ANY",
       "violationState": "FAIL",
       "policyConditions": [
         {
           "subject": "SEVERITY",
           "operator": "IS",
           "value": "CRITICAL"
         }
       ]
     }'

# Create a license policy (denylist approach)
curl -X PUT "${DTRACK_URL}/api/v1/policy" \
     -H "X-Api-Key: ${API_KEY}" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "No Copyleft Licenses",
       "operator": "ANY",
       "violationState": "WARN",
       "policyConditions": [
         {
           "subject": "LICENSE_GROUP",
           "operator": "IS",
           "value": "Copyleft"
         }
       ]
     }'

# Create operational policy (block specific component)
curl -X PUT "${DTRACK_URL}/api/v1/policy" \
     -H "X-Api-Key: ${API_KEY}" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "Block Vulnerable Log4j",
       "operator": "ALL",
       "violationState": "FAIL",
       "policyConditions": [
         {
           "subject": "COORDINATES",
           "operator": "MATCHES",
           "value": "{\"group\":\"org.apache.logging.log4j\",\"name\":\"log4j-core\",\"version\":\"<2.17.0\"}"
         }
       ]
     }'

策略条件主体

• AGE - 组件年龄
• COORDINATES - Group/Name/Version
• CPE - 通用平台枚举
• CWE - 通用弱点枚举
• EPSS - 漏洞利用预测评分系统
• LICENSE - 特定许可证
• LICENSE_GROUP - 许可证类别
• PACKAGE_URL - 软件包 URL（PURL）
• SEVERITY - 漏洞严重性
• SWID_TAGID - 软件 ID 标签
• VERSION - 组件版本
• COMPONENT_HASH - MD5、SHA、Blake 哈希

---

6. 通知与集成

Webhook 配置

{
  "notification": {
    "level": "INFORMATIONAL",
    "scope": "PORTFOLIO",
    "group": "NEW_VULNERABILITY",
    "timestamp": "2024-01-15T10:30:00Z",
    "subject": {
      "component": {
        "name": "log4j-core",
        "version": "2.14.1"
      },
      "vulnerability": {
        "vulnId": "CVE-2021-44228",
        "severity": "CRITICAL"
      },
      "affectedProjects": [...]
    }
  }
}

通知组

• NEW_VULNERABILITY - 发现新漏洞
• NEW_VULNERABLE_DEPENDENCY - 添加了新的易受攻击组件
• ANALYSIS_DECISION_CHANGE - 审计决定已修改
• POLICY_VIOLATION - 检测到策略违规
• BOM_CONSUMED - 已处理 SBOM
• BOM_PROCESSED - SBOM 分析已完成
• VEX_CONSUMED - 已处理 VEX 文档

集成目标

• Slack/Teams：直接支持 webhook
• Email：SMTP 配置
• Jira：原生集成
• DefectDojo：漏洞汇总
• Fortify SSC：AppSec 平台
• ThreadFix：漏洞管理
• Kenna Security：风险优先级排序

---

7. SBOM 生成工具

按语言/生态系统划分

语言	工具	命令
Java/Maven	cyclonedx-maven-plugin	mvn org.cyclonedx:cyclonedx-maven-plugin:makeAggregateBom
Java/Gradle	cyclonedx-gradle-plugin	gradle cyclonedxBom
Node.js	@cyclonedx/cyclonedx-npm	npx @cyclonedx/cyclonedx-npm --output-file bom.json
Python	cyclonedx-py	cyclonedx-py -r requirements.txt -o bom.json
Go	cyclonedx-gomod	cyclonedx-gomod mod -json -output bom.json
.NET	CycloneDX	dotnet CycloneDX <project> -o bom.json
Rust	cargo-cyclonedx	cargo cyclonedx -f json
容器	Syft	syft <image> -o cyclonedx-json > bom.json

通用工具

# Syft - multi-ecosystem SBOM generator
syft packages dir:. -o cyclonedx-json > bom.json

# Trivy - with vulnerability scanning
trivy fs --format cyclonedx --output bom.json .

# cdxgen - comprehensive generator
cdxgen -o bom.json

---

8. 最佳实践

部署

1. 生产环境使用外部 PostgreSQL（而不是内嵌 H2）
2. 分配充足的 RAM（API 服务至少需要 4.5GB）
3. 为 /data 目录配置持久化存储
4. 使用有效证书启用 TLS
5. 定期备份数据库和配置

运维

1. 在 CI/CD 中生成 SBOM - 在构建时自动生成
2. 启用 OSS Index Analyzer - PURL 扫描所必需
3. 在本地镜像 NVD - 提升性能
4. 在流水线中使用同步上传，以便立即获得反馈
5. 实施策略门禁 - 违规时让构建失败

安全

1. 定期轮换 API 密钥
2. 使用权限最小化的团队范围密钥
3. 启用审计日志记录以满足合规要求
4. 为企业身份验证配置 OIDC/LDAP
5. 在合同中要求供应商提供 SBOM

性能

1. 在非工作时间安排耗时操作
2. 对大型 API 响应使用分页
3. 为频繁访问的数据实现缓存
4. 监控分析器队列深度
5. 通过运行多个 API 服务副本进行横向扩展

---

9. 故障排除

常见问题

问题	原因	解决方案
未发现漏洞	未启用 OSS Index	在 Admin > Analyzers 中启用，并获取 API token
分析器未运行	6 小时调度周期	重新上传 SBOM，或等待计划运行
容器崩溃	RAM 不足	为 API server 分配至少 4.5GB
413 Request Entity Too Large	Nginx 请求体大小限制	添加 nginx.ingress.kubernetes.io/proxy-body-size: "100m"
PKIX path building error	自签名证书	在设置中配置内部 CA
LDAP 同步延迟	异步作业队列	等待或手动创建账户
服务在 1-2 周后停止	操作系统清理临时文件	设置 -Djava.io.tmpdir=/path/to/tmpdir

调试命令

# Check API server logs
docker logs -f dependency-track-apiserver

# Verify database connectivity
docker exec -it dependency-track-apiserver \
  curl -s http://localhost:8080/api/version

# Check analyzer status
curl -s -H "X-Api-Key: ${API_KEY}" \
     "${DTRACK_URL}/api/v1/configProperty?groupName=analyzer"

# Monitor mirror status
curl -s -H "X-Api-Key: ${API_KEY}" \
     "${DTRACK_URL}/api/v1/mirror/nvd"

# Health check
curl -s "${DTRACK_URL}/api/version"

性能调优

# JVM settings for high-load environments
environment:
  JAVA_OPTIONS: >-
    -Xms8g
    -Xmx16g
    -XX:+UseG1GC
    -XX:MaxGCPauseMillis=200
    -XX:+ParallelRefProcEnabled

---

10. 参考文件

更多模板和示例位于 references/ 目录中：

部署：

• references/deployment/docker-compose-production.yaml - 用于生产环境的 Docker Compose
• references/deployment/helm-values.yaml - 适用于 v4.x 的 Helm values（Chart v0.40.0）
• references/deployment/helm-values-hyades.yaml - 适用于 Hyades v5.x 的 Helm values（Chart v0.10.0）
• references/deployment/kubernetes-manifests/ - 原始 Kubernetes 清单

CI/CD 集成：

• references/cicd/jenkinsfile - Jenkins Pipeline 示例
• references/cicd/github-action.yaml - GitHub Actions 工作流
• references/cicd/gitlab-ci.yaml - GitLab CI/CD 流水线
• references/cicd/azure-pipeline.yaml - Azure DevOps Pipeline

API 和脚本：

• references/api/python-client.py - Python 客户端库示例
• references/api/bash-scripts/ - 用于常见操作的 Shell 脚本

策略：

• references/policies/security-policies.json - 安全策略模板
• references/policies/license-policies.json - 许可证策略模板
• references/policies/operational-policies.json - 运维策略模板

故障排除：

• references/troubleshooting.md - 常见问题及解决方案

---

相关技能

• defectdojo-skill - 漏洞管理集成
• argocd-skill - Dependency-Track 的 GitOps 部署
• quality-guardian - 安全测试集成

---

注意事项

• 上传 BOM 时未提供 projectVersion 会覆盖先前的 BOM： 上传到同一项目名称但未指定不同版本时，会替换清单，而不是进行版本管理。务必传入 projectVersion（提交 SHA 或 semver），并考虑在 monorepo 中使用 parentName/parentVersion。
• OSS Index 分析器每 6 小时运行一次，不会在上传时运行： 新上传的 SBOM 可能数小时内显示零漏洞，因为分析器尚未扫描。重新上传 BOM 或等待——不要根据即时 UI 状态就断定“没有漏洞”。
• /api/v1/oidc/mapping 需要 UUID 字符串，而不是对象： 发送 {"team": {"uuid": "..."}, "group": {"uuid": "..."}} 会返回 400。请使用 {"team": "<uuid>", "group": "<uuid>"}。只有该组的用户至少登录一次后，OIDC 组才会显示在 UI 中。
• 首次启动时镜像 NVD 需要 10-30+ 分钟： 在此期间 API 可以正常工作，但漏洞匹配并不完整。不要进行基准测试，也不要在日志显示 NVD 镜像完成之前上线流水线集成——过早扫描会错误地显示没有漏洞。
• API server 至少需要 4.5GB RAM： 低于此值时，JVM 会在镜像过程中发生 OOM，导致数据库仅完成部分初始化。恢复通常需要清空 /data 并重启。扩容之前，请相应设置 Helm apiServer.resources.requests.memory。
• NGINX Ingress 的默认请求体大小限制会以 413 拒绝大型 SBOM： monorepo 或容器 BOM 经常超过 1MB。请在 Ingress 注解中添加 nginx.ingress.kubernetes.io/proxy-body-size: "100m"。