dependency-track-skill

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Dependency-Track Skill

Dependency-Track 技能指南

Comprehensive guide for implementing, deploying, and operating Dependency-Track - an intelligent Software Composition Analysis (SCA) platform that identifies and reduces risk in the software supply chain through SBOM management.

Current Versions:

Helm Chart:
```
0.40.0
```
App Version:
```
4.13.6
```

Helm Repository:

https://dependencytrack.github.io/helm-charts

这是一份关于部署、实施和运维Dependency-Track的全面指南——它是一款智能软件成分分析（SCA）平台，通过SBOM管理识别并降低软件供应链中的风险。

当前版本：

Helm Chart:
```
0.40.0
```
应用版本:
```
4.13.6
```

Helm仓库:

https://dependencytrack.github.io/helm-charts

Overview

概述

Dependency-Track is an API-first platform that:

Consumes and produces CycloneDX SBOMs and VEX documents
Monitors components for known vulnerabilities across the entire portfolio
Integrates with NVD, GitHub Advisories, OSS Index, Snyk, Trivy, OSV, and VulnDB
Provides policy enforcement for security, license, and operational compliance
Supports OAuth 2.0, OIDC, LDAP, Active Directory authentication
Supports EPSS (Exploit Prediction Scoring System) for prioritization
Identifies APIs and external service components

Dependency-Track是一个API优先的平台，具备以下能力：

导入和生成CycloneDX SBOM及VEX文档
监控全产品线中组件的已知漏洞
与NVD、GitHub Advisories、OSS Index、Snyk、Trivy、OSV和VulnDB集成
提供安全、许可证及运营合规的策略强制执行
支持OAuth 2.0、OIDC、LDAP、Active Directory认证
支持EPSS（漏洞利用预测评分系统）进行风险优先级排序
识别API和外部服务组件

Quick Reference

快速参考

Resource	Path
Deployment Templates	`references/deployment/`
CI/CD Integration	`references/cicd/`
API Examples	`references/api/`
Policy Templates	`references/policies/`
Troubleshooting	`references/troubleshooting.md`

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

1. Deployment Options

1. 部署选项

Docker Compose (Recommended for Production)

Docker Compose（生产环境推荐）

bash

undefined

bash

undefined

Download official docker-compose

下载官方docker-compose文件

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

Start services

启动服务

docker compose up -d

Access UI at http://localhost:8080

通过http://localhost:8080访问UI

Default credentials: admin / admin

默认凭据：admin / admin


**Minimum Requirements:**
- API Server: 4.5GB RAM, 2 CPU cores
- Frontend: 512MB RAM, 1 CPU core

**Recommended Requirements:**
- API Server: 16GB RAM, 4 CPU cores
- Frontend: 1GB RAM, 2 CPU cores


**最低要求：**
- API服务器：4.5GB内存，2核CPU
- 前端：512MB内存，1核CPU

**推荐配置：**
- API服务器：16GB内存，4核CPU
- 前端：1GB内存，2核CPU

Kubernetes with Helm

Kubernetes + Helm部署

bash

undefined

bash

undefined

Add Helm repository

添加Helm仓库

helm repo add dependency-track https://dependencytrack.github.io/helm-charts helm repo update

View available charts

查看可用的chart

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


**Available Charts:**
| Chart | Description | Status |
|-------|-------------|--------|
| `dependency-track/dependency-track` | Monolithic deployment (v4.x) | Production Ready |
| `dependency-track/hyades` | Microservices deployment (v5.x) | Incubating (Not GA) |

See `references/deployment/` for complete manifests and Helm values.

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配置请查看`references/deployment/`目录。

ArgoCD GitOps Deployment (AKS)

ArgoCD GitOps部署（AKS环境）

For enterprise Kubernetes deployments using ArgoCD with multi-source ApplicationSets:

Directory Structure:

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
      cafehyna-dev/
        values.yaml             # Environment-specific Helm values
        secretproviderclass.yaml # Azure Key Vault CSI integration

ApplicationSet Example (Multi-Source):

yaml

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: dependency-track
  namespace: argocd
spec:
  generators:
    - list:
        elements:
          - cluster: cafehyna-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):

yaml

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 Instance Tolerations (Cost Optimization):

yaml

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

Key ignoreDifferences for ArgoCD:

yaml

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

See

references/deployment/argocd/

for complete ApplicationSet and values examples.

适用于使用ArgoCD多源ApplicationSets的企业级Kubernetes部署：

目录结构：

infra-team/
  applicationset/
    dependency-track.yaml       # ArgoCD ApplicationSet定义
argo-cd-helm-values/
  kube-addons/
    dependency-track/
      azure-ad-setup.sh         # Azure AD应用注册脚本
      cafehyna-dev/
        values.yaml             # 环境专属Helm配置
        secretproviderclass.yaml # Azure Key Vault CSI集成配置

ApplicationSet示例（多源）：

yaml

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: dependency-track
  namespace: argocd
spec:
  generators:
    - list:
        elements:
          - cluster: cafehyna-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:
        # 源1：官方仓库的Helm chart
        - 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
        # 源2：配置仓库引用
        - repoURL: https://your-git-repo.git
          targetRevision: "{{branch}}"
          ref: values
        # 源3：额外清单（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驱动（SecretProviderClass）：

yaml

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抢占式实例容忍配置（成本优化）：

yaml

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关键忽略差异配置：

yaml

ignoreDifferences:
  # StatefulSet VolumeClaimTemplates（ServerSideApply漂移）
  - group: apps
    kind: StatefulSet
    jqPathExpressions:
      - .spec.volumeClaimTemplates[]?.apiVersion
      - .spec.volumeClaimTemplates[]?.kind
      - .spec.volumeClaimTemplates[]?.status
  # PVC动态字段
  - group: ""
    kind: PersistentVolumeClaim
    jsonPointers:
      - /status
      - /spec/volumeName
  # Azure Key Vault同步的密钥
  - group: ""
    kind: Secret
    name: dependency-track-secrets
    jsonPointers:
      - /data

完整的ApplicationSet和配置示例请查看

references/deployment/argocd/

目录。

Hyades (Next-Generation Architecture)

Hyades（下一代架构）

Hyades is the incubating project for Dependency-Track v5, decoupling the monolithic API server into separate, scalable microservices.

Components:

```
hyades-apiserver
```
- Core API server
```
hyades-frontend
```
- Web UI
```
hyades-notification-publisher
```
- Notification handling
```
hyades-repository-meta-analyzer
```
- Repository metadata analysis
```
hyades-vulnerability-analyzer
```
- Vulnerability scanning

Requirements:

External PostgreSQL database
Apache Kafka cluster
Kubernetes 1.19+

bash

undefined

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

组件：

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

要求：

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

bash

undefined

Install Hyades (NOT PRODUCTION READY)

安装Hyades（非生产可用）

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"


> **Warning:** Hyades is NOT generally available. Breaking changes may occur without notice. Use only in test environments. GA roadmap: https://github.com/DependencyTrack/hyades/issues/860

---


> **警告：** Hyades尚未正式发布。可能会出现不兼容变更，且不提前通知。仅可在测试环境使用。正式发布路线图：https://github.com/DependencyTrack/hyades/issues/860

---

2. Initial Configuration

2. 初始配置

First-Time Setup

首次设置

Wait for initialization (10-30+ minutes):
- Creates default users, teams, permissions
- Mirrors NVD, GitHub Advisories (do not interrupt)
- Check progress:
```
docker logs -f dependency-track-apiserver
```
Change default password immediately after first login
Enable analyzers in Administration > Analyzers:
- Internal Analyzer (built-in)
- OSS Index (requires API token from ossindex.sonatype.org)
- Snyk (optional, requires token)
- Trivy (optional)

等待初始化完成（10-30分钟以上）：
- 创建默认用户、团队、权限
- 同步NVD、GitHub Advisories数据（请勿中断）
- 查看进度：
```
docker logs -f dependency-track-apiserver
```
首次登录后立即修改默认密码
在管理页面启用分析器：
- 内置分析器（Internal Analyzer）
- OSS Index（需要从ossindex.sonatype.org获取API令牌）
- Snyk（可选，需要令牌）
- Trivy（可选）

Database Configuration (Production)

生产环境数据库配置

yaml

undefined

yaml

undefined

docker-compose override for PostgreSQL

docker-compose覆盖配置（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}

undefined

undefined

LDAP/Active Directory

LDAP/Active Directory配置

properties

undefined

properties

undefined

Active Directory configuration

Active Directory配置

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=%s@example.com 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}))

undefined

undefined

OpenID Connect (Azure AD, Okta, Keycloak)

OpenID Connect（Azure AD、Okta、Keycloak）配置

properties

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

properties

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 Groups Integration (Detailed Guide)

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

How OIDC Groups Work in Dependency-Track

Dependency-Track中OIDC组的工作原理

Group Claim Flow:
- User authenticates via Azure AD
- Azure AD returns ID token with
```
groups
```
  claim (array of Group Object IDs)
- Dependency-Track reads the
```
groups
```
  claim (configured via
```
ALPINE_OIDC_TEAMS_CLAIM
```
  )
- Groups are matched to Teams via OpenID Connect Groups mappings
Important Behavior:
- Groups only appear in Administration > OpenID Connect Groups after a user from that group authenticates
- Teams must exist before group mapping (auto-created if
```
ALPINE_OIDC_TEAM_SYNCHRONIZATION=true
```
  )
- Group Object IDs (UUIDs) are used, not display names

组声明流程：
- 用户通过Azure AD完成认证
- Azure AD返回包含
```
groups
```
  声明的ID令牌（组对象ID数组）
- Dependency-Track读取
```
groups
```
  声明（通过
```
ALPINE_OIDC_TEAMS_CLAIM
```
  配置）
- 组通过OpenID Connect组映射匹配到平台内的团队
重要特性：
- 只有当该组的用户完成认证后，组才会出现在“管理 > OpenID Connect组”页面
- 组映射前必须先存在对应团队（若
```
ALPINE_OIDC_TEAM_SYNCHRONIZATION=true
```
  则会自动创建）
- 使用的是组对象ID（UUID），而非显示名称

Method 1: API-Based Setup (Recommended)

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

Use the REST API to create teams, OIDC groups, and mappings:

bash

undefined

使用REST API创建团队、OIDC组及映射关系：

bash

undefined

Set environment variables

设置环境变量

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

Azure AD Group Object ID

Azure AD组对象ID

AZURE_GROUP_ID="31d6daa5-5cc2-4e5f-9bf5-75ee8e09198c"

1. Create a Team (if doesn't exist)

1. 创建团队（若不存在）

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

2. 获取团队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)

3. 创建OIDC组（映射前必须创建）

NOTE: Use Azure AD Group Object ID as both uuid and name

注意：使用Azure AD组对象ID作为uuid和名称

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

4. 获取已创建的OIDC组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

5. 创建OIDC组到团队的映射

IMPORTANT: Use UUID strings directly, NOT objects

重要：直接使用UUID字符串，而非对象格式

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

6. 为团队分配权限

curl -X POST "${DTRACK_URL}/api/v1/permission/BOM_UPLOAD/team/${TEAM_UUID}"
-H "X-Api-Key: ${DTRACK_API_KEY}"


> **IMPORTANT:** The `/api/v1/oidc/mapping` endpoint expects UUID **strings**, not objects.
> Using `{"team": {"uuid": "..."}, "group": {"uuid": "..."}}` will return HTTP 400.

curl -X POST "${DTRACK_URL}/api/v1/permission/BOM_UPLOAD/team/${TEAM_UUID}"
-H "X-Api-Key: ${DTRACK_API_KEY}"


> **重要提示：** `/api/v1/oidc/mapping`接口要求传入UUID**字符串**，而非对象。
> 使用`{"team": {"uuid": "..."}, "group": {"uuid": "..."}}`格式会返回HTTP 400错误。

Verifying OIDC Group Mappings

验证OIDC组映射

Use these commands to verify that OIDC groups are properly mapped to teams:

bash

undefined

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

bash

undefined

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

列出所有带有OIDC组映射的团队

/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

列出Dependency-Track中已注册的所有OIDC组

/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

检查特定团队的OIDC映射

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 Output (cafehyna-dev cluster):**
```json
[
  {"team": "Administrators", "oidcGroups": ["31d6daa5-5cc2-4e5f-9bf5-75ee8e09198c"]},
  {"team": "Auditors", "oidcGroups": ["39d0ddb2-8a0d-47c9-bc55-1993aadf7fe8"]},
  {"team": "Developers", "oidcGroups": ["7144c503-7934-40fe-99e2-f45f67cb383e"]},
  {"team": "Moderators", "oidcGroups": ["d34a2ea3-34c9-4744-a031-4e4a55d72746"]},
  {"team": "ReadOnly", "oidcGroups": ["7109c419-028e-4b7b-8246-66517d512c3c"]}
]

Note: Use full paths (
/usr/bin/curl
,
/usr/bin/jq
) to avoid shell alias issues in automated environments.


**示例输出（cafehyna-dev集群）：**
```json
[
  {"team": "Administrators", "oidcGroups": ["31d6daa5-5cc2-4e5f-9bf5-75ee8e09198c"]},
  {"team": "Auditors", "oidcGroups": ["39d0ddb2-8a0d-47c9-bc55-1993aadf7fe8"]},
  {"team": "Developers", "oidcGroups": ["7144c503-7934-40fe-99e2-f45f67cb383e"]},
  {"team": "Moderators", "oidcGroups": ["d34a2ea3-34c9-4744-a031-4e4a55d72746"]},
  {"team": "ReadOnly", "oidcGroups": ["7109c419-028e-4b7b-8246-66517d512c3c"]}
]

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

Method 2: Manual UI Configuration

方法2：手动UI配置

Create Teams:
- Go to Administration > Access Management > Teams
- Create teams: Administrators, Moderators, Auditors, Developers
- Assign permissions to each team
Map Groups:
- Go to Administration > Access Management > OpenID Connect Groups
- Click "Create Group"
- Enter Azure AD Group Object ID (e.g.,
```
31d6daa5-5cc2-4e5f-9bf5-75ee8e09198c
```
  )
- Select Team to map to
- Save

创建团队：
- 进入“管理 > 访问管理 > 团队”
- 创建团队：Administrators、Moderators、Auditors、Developers
- 为每个团队分配权限
组映射：
- 进入“管理 > 访问管理 > OpenID Connect组”
- 点击“创建组”
- 输入Azure AD组对象ID（例如：
```
31d6daa5-5cc2-4e5f-9bf5-75ee8e09198c
```
  ）
- 选择要映射的团队
- 保存

Retrieving Azure AD Group Object IDs

获取Azure AD组对象ID

bash

undefined

bash

undefined

List all Azure AD groups with DependencyTrack in name

列出所有名称包含DependencyTrack的Azure AD组

az ad group list --filter "startswith(displayName, 'G-Usuarios-DependencyTrack')"
--query "[].{name:displayName, id:id}" -o table

Get specific group Object ID

获取特定组的对象ID

az ad group show --group "G-Usuarios-DependencyTrack-Admin" --query id -o tsv

undefined

az ad group show --group "G-Usuarios-DependencyTrack-Admin" --query id -o tsv

undefined

Validating Group Claims in ID Token

验证ID令牌中的组声明

Decode JWT Token (use jwt.io):
- Login to Dependency-Track
- Capture network request to
```
/api/v1/oidc/callback
```
- Decode the
```
id_token
```
  to verify
```
groups
```
  claim contains expected UUIDs
Azure AD Token Configuration Checklist:
- App Registration has
```
groupMembershipClaims: SecurityGroup
```
- Optional Claims include
```
groups
```
  in ID Token
- API Permissions:
```
GroupMember.Read.All
```
  (delegated)
- Admin consent granted

解码JWT令牌（使用jwt.io）：
- 登录Dependency-Track
- 捕获
```
/api/v1/oidc/callback
```
  的网络请求
- 解码
```
id_token
```
  验证
```
groups
```
  声明是否包含预期的UUID
Azure AD令牌配置检查清单：
- 应用注册已设置
```
groupMembershipClaims: SecurityGroup
```
- 可选声明已将
```
groups
```
  添加到ID令牌
- API权限已添加
```
GroupMember.Read.All
```
  （委托权限）
- 已授予管理员同意

Environment Variables Reference

环境变量参考

Variable	Description	Example
`ALPINE_OIDC_ENABLED`	Enable OIDC	`true`
`ALPINE_OIDC_ISSUER`	Azure AD issuer URL	`https://login.microsoftonline.com/{tenant}/v2.0`
`ALPINE_OIDC_CLIENT_ID`	App Registration Client ID	From Key Vault
`ALPINE_OIDC_CLIENT_SECRET`	App Registration Secret	From Key Vault
`ALPINE_OIDC_USERNAME_CLAIM`	Claim for username	`preferred_username`
`ALPINE_OIDC_TEAMS_CLAIM`	Claim for groups	`groups`
`ALPINE_OIDC_USER_PROVISIONING`	Auto-create users	`true`
`ALPINE_OIDC_TEAM_SYNCHRONIZATION`	Auto-sync team membership	`true`

变量	描述	示例
`ALPINE_OIDC_ENABLED`	启用OIDC	`true`
`ALPINE_OIDC_ISSUER`	Azure AD颁发者URL	`https://login.microsoftonline.com/{tenant}/v2.0`
`ALPINE_OIDC_CLIENT_ID`	应用注册客户端ID	从Key Vault获取
`ALPINE_OIDC_CLIENT_SECRET`	应用注册密钥	从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 Integration

3. CI/CD集成

Workflow: BOM Upload Pipeline

工作流：SBOM上传流水线

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

┌─────────────┐     ┌─────────────┐     ┌──────────────────┐
│   构建项目   │────▶│ 生成CycloneDX│────▶│ 上传至Dependency-Track │
│             │     │    SBOM     │     │                  │
└─────────────┘     └─────────────┘     └──────────────────┘
                    │                        │
                    ▼                        ▼
                    ┌─────────────┐     ┌──────────────────┐
                    │   终止构建？ │◀────│   策略评估       │
                    │             │     │                  │
                    └─────────────┘     └──────────────────┘

Jenkins Pipeline

Jenkins流水线

groovy

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
                )
            }
        }
    }
}

groovy

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

yaml

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

Official GitHub Action Options (
DependencyTrack/gh-upload-sbom@v3
):

Parameter	Required	Default	Description
`serverHostname`	Yes	-	Dependency-Track server URL
`apiKey`	Yes	-	API key with BOM_UPLOAD permission
`projectName`	Yes	-	Name of the project
`projectVersion`	Yes	-	Version of the project
`bomFilename`	Yes	-	Path to CycloneDX SBOM file
`autoCreate`	No	`false`	Auto-create project if not exists
`parentName`	No	-	Parent project name
`parentVersion`	No	-	Parent project version
`projectUuid`	No	-	Use UUID instead of name/version

yaml

name: SBOM安全扫描

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

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

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

      - name: 上传至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

yaml

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

yaml

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 Pipeline

Azure DevOps流水线

yaml

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}\"}"

yaml

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: '上传SBOM至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 Usage

4. REST API使用

Authentication

认证

Generate API keys in Administration > Access Management > Teams > [Team] > API Keys.

bash

undefined

在“管理 > 访问管理 > 团队 > [目标团队] > API密钥”页面生成API密钥。

bash

undefined

All API calls require the X-Api-Key header

所有API请求都需要携带X-Api-Key请求头

curl -H "X-Api-Key: YOUR_API_KEY"
https://dtrack.example.com/api/v1/project

undefined

curl -H "X-Api-Key: YOUR_API_KEY"
https://dtrack.example.com/api/v1/project

undefined

OpenAPI Specification

OpenAPI规范

Access at:

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

Note: Use port 8081 (API server), not 8080 (frontend).

访问地址：

JSON格式：
```
http://localhost:8081/api/openapi.json
```
YAML格式：
```
http://localhost:8081/api/openapi.yaml
```

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

Common API Operations

常见API操作

bash

undefined

bash

undefined

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)

上传SBOM（Base64编码）

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)

上传SBOM（multipart形式，无需编码）

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 "bom=@bom.json"

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. Policy Configuration

5. 策略配置

Policy Types

策略类型

Type	Purpose	Example Conditions
License	Control allowed/forbidden licenses	Apache-2.0 allowed, GPL-3.0 forbidden
Security	Vulnerability severity thresholds	No Critical, max 5 High
Operational	Component allowlists/denylists	Block log4j < 2.17.0

类型	用途	示例条件
许可证	控制允许/禁止的许可证	允许Apache-2.0，禁止GPL-3.0
安全	漏洞严重程度阈值	不允许Critical级漏洞，High级漏洞最多5个
运营	组件白名单/黑名单	阻止log4j < 2.17.0版本

Creating Policies via API

通过API创建策略

bash

undefined

bash

undefined

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" } ] }'

curl -X PUT "${DTRACK_URL}/api/v1/policy"
-H "X-Api-Key: ${API_KEY}"
-H "Content-Type: application/json"
-d '{ "name": "禁止Critical级漏洞", "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" } ] }'

curl -X PUT "${DTRACK_URL}/api/v1/policy"
-H "X-Api-Key: ${API_KEY}"
-H "Content-Type: application/json"
-d '{ "name": "禁止Copyleft许可证", "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"}" } ] }'

undefined

curl -X PUT "${DTRACK_URL}/api/v1/policy"
-H "X-Api-Key: ${API_KEY}"
-H "Content-Type: application/json"
-d '{ "name": "阻止存在漏洞的Log4j版本", "operator": "ALL", "violationState": "FAIL", "policyConditions": [ { "subject": "COORDINATES", "operator": "MATCHES", "value": "{"group":"org.apache.logging.log4j","name":"log4j-core","version":"<2.17.0"}" } ] }'

undefined

Policy Condition Subjects

策略条件主题

```
AGE
```
- Component age
```
COORDINATES
```
- Group/Name/Version
```
CPE
```
- Common Platform Enumeration
```
CWE
```
- Common Weakness Enumeration
```
EPSS
```
- Exploit Prediction Scoring System
```
LICENSE
```
- Specific license
```
LICENSE_GROUP
```
- License category
```
PACKAGE_URL
```
- Package URL (PURL)
```
SEVERITY
```
- Vulnerability severity
```
SWID_TAGID
```
- Software ID tag
```
VERSION
```
- Component version
```
COMPONENT_HASH
```
- MD5, SHA, Blake hashes

```
AGE
```
- 组件使用时长
```
COORDINATES
```
- 组/名称/版本
```
CPE
```
- 通用平台枚举
```
CWE
```
- 通用弱点枚举
```
EPSS
```
- 漏洞利用预测评分系统
```
LICENSE
```
- 特定许可证
```
LICENSE_GROUP
```
- 许可证类别
```
PACKAGE_URL
```
- 包URL（PURL）
```
SEVERITY
```
- 漏洞严重程度
```
SWID_TAGID
```
- 软件ID标签
```
VERSION
```
- 组件版本
```
COMPONENT_HASH
```
- MD5、SHA、Blake哈希值

6. Notifications & Integrations

6. 通知与集成

Webhook Configuration

Webhook配置

json

{
  "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": [...]
    }
  }
}

json

{
  "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": [...]
    }
  }
}

Notification Groups

通知组

```
NEW_VULNERABILITY
```
- New vulnerability identified
```
NEW_VULNERABLE_DEPENDENCY
```
- New vulnerable component added
```
ANALYSIS_DECISION_CHANGE
```
- Audit decision modified
```
POLICY_VIOLATION
```
- Policy violation detected
```
BOM_CONSUMED
```
- SBOM processed
```
BOM_PROCESSED
```
- SBOM analysis complete
```
VEX_CONSUMED
```
- VEX document processed

```
NEW_VULNERABILITY
```
- 识别到新漏洞
```
NEW_VULNERABLE_DEPENDENCY
```
- 添加了新的存在漏洞的组件
```
ANALYSIS_DECISION_CHANGE
```
- 审计决策被修改
```
POLICY_VIOLATION
```
- 检测到策略违规
```
BOM_CONSUMED
```
- SBOM已被处理
```
BOM_PROCESSED
```
- SBOM分析完成
```
VEX_CONSUMED
```
- VEX文档已被处理

Integration Targets

集成目标

Slack/Teams: Direct webhook support
Email: SMTP configuration
Jira: Native integration
DefectDojo: Vulnerability aggregation
Fortify SSC: AppSec platform
ThreadFix: Vulnerability management
Kenna Security: Risk prioritization

Slack/Teams：直接支持webhook
邮件：SMTP配置
Jira：原生集成
DefectDojo：漏洞聚合
Fortify SSC：应用安全平台
ThreadFix：漏洞管理
Kenna Security：风险优先级排序

7. SBOM Generation Tools

7. SBOM生成工具

By Language/Ecosystem

按语言/生态系统分类

Language	Tool	Command
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`
Container	Syft	`syft <image> -o cyclonedx-json > bom.json`

语言	工具	命令
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`

Universal Tools

通用工具

bash

undefined

bash

undefined

Syft - multi-ecosystem SBOM generator

Syft - 多生态系统SBOM生成器

syft packages dir:. -o cyclonedx-json > bom.json

Trivy - with vulnerability scanning

Trivy - 带漏洞扫描功能

trivy fs --format cyclonedx --output bom.json .

cdxgen - comprehensive generator

cdxgen - 全面的SBOM生成器

cdxgen -o bom.json

---

cdxgen -o bom.json

---

8. Best Practices

8. 最佳实践

Deployment

部署

Use external PostgreSQL for production (not embedded H2)
Allocate sufficient RAM (minimum 4.5GB for API server)
Configure persistent storage for
```
/data
```
directory
Enable TLS with proper certificates
Set up regular backups of database and configuration

生产环境使用外部PostgreSQL（而非内置的H2数据库）
分配足够的内存（API服务器最低4.5GB）
配置持久化存储用于
```
/data
```
目录
启用TLS并使用有效证书
定期备份数据库和配置

Operations

运维

Generate SBOMs in CI/CD - automate at build time
Enable OSS Index Analyzer - required for PURL-based scanning
Mirror NVD locally - improves performance
Use synchronous uploads in pipelines for immediate feedback
Implement policy gates - fail builds on violations

在CI/CD中自动生成SBOM - 构建阶段自动完成
启用OSS Index分析器 - 基于PURL的扫描需要此分析器
本地同步NVD数据 - 提升性能
流水线中使用同步上传 - 立即获取反馈
实现策略门禁 - 出现违规时终止构建

Security

安全

Rotate API keys regularly
Use team-scoped keys with minimal permissions
Enable audit logging for compliance
Configure OIDC/LDAP for enterprise authentication
Contractually require SBOMs from vendors

定期轮换API密钥
使用团队级密钥并分配最小权限
启用审计日志以满足合规要求
配置OIDC/LDAP用于企业级认证
通过合同要求供应商提供SBOM

Performance

性能

Schedule heavy operations during off-hours
Use pagination for large API responses
Implement caching for frequently accessed data
Monitor analyzer queue depth
Scale horizontally with multiple API server replicas

在非高峰时段执行重操作
对大型API响应使用分页
为频繁访问的数据实现缓存
监控分析器队列深度
通过多API服务器副本实现水平扩展

9. Troubleshooting

9. 故障排查

Common Issues

常见问题

Issue	Cause	Solution
No vulnerabilities found	OSS Index not enabled	Enable in Admin > Analyzers, get API token
Analyzer not running	6-hour schedule	Re-upload SBOM or wait for scheduled run
Container crashes	Insufficient RAM	Allocate minimum 4.5GB to API server
413 Request Entity Too Large	Nginx body size limit	Add `nginx.ingress.kubernetes.io/proxy-body-size: "100m"`
PKIX path building error	Self-signed certificates	Configure internal CA in settings
LDAP sync delays	Async job queue	Wait or manually create accounts
Service stops after 1-2 weeks	OS temp cleanup	Set `-Djava.io.tmpdir=/path/to/tmpdir`

问题	原因	解决方案
未找到漏洞	未启用OSS Index	在管理 > 分析器中启用，并获取API令牌
分析器未运行	6小时执行一次的调度	重新上传SBOM或等待调度执行
容器崩溃	内存不足	为API服务器分配至少4.5GB内存
413请求实体过大	Nginx请求体大小限制	添加 `nginx.ingress.kubernetes.io/proxy-body-size: "100m"` 配置
PKIX路径构建错误	自签名证书	在设置中配置内部CA证书
LDAP同步延迟	异步任务队列	等待或手动创建账号
服务运行1-2周后停止	系统临时文件清理	设置 `-Djava.io.tmpdir=/path/to/tmpdir`

Debug Commands

调试命令

bash

undefined

bash

undefined

Check API server logs

查看API服务器日志

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"

undefined

curl -s "${DTRACK_URL}/api/version"

undefined

Performance Tuning

性能调优

yaml

undefined

yaml

undefined

JVM settings for high-load environments

高负载环境下的JVM配置

environment: JAVA_OPTIONS: >- -Xms8g -Xmx16g -XX:+UseG1GC -XX:MaxGCPauseMillis=200 -XX:+ParallelRefProcEnabled

---

environment: JAVA_OPTIONS: >- -Xms8g -Xmx16g -XX:+UseG1GC -XX:MaxGCPauseMillis=200 -XX:+ParallelRefProcEnabled

---

10. Reference Files

10. 参考文件

Additional templates and examples are in the

references/

directory:

Deployment:

references/deployment/docker-compose-production.yaml

- Docker Compose for production

```
references/deployment/helm-values.yaml
```
- Helm values for v4.x (Chart v0.40.0)

references/deployment/helm-values-hyades.yaml

- Helm values for Hyades v5.x (Chart v0.10.0)

references/deployment/kubernetes-manifests/

- Raw Kubernetes manifests

CI/CD Integration:

```
references/cicd/jenkinsfile
```
- Jenkins Pipeline example
```
references/cicd/github-action.yaml
```
- GitHub Actions workflow
```
references/cicd/gitlab-ci.yaml
```
- GitLab CI/CD pipeline
```
references/cicd/azure-pipeline.yaml
```
- Azure DevOps Pipeline

API & Scripts:

```
references/api/python-client.py
```
- Python client library example
```
references/api/bash-scripts/
```
- Shell scripts for common operations

Policies:

references/policies/security-policies.json

- Security policy templates

references/policies/license-policies.json

- License policy templates

references/policies/operational-policies.json

- Operational policy templates

Troubleshooting:

```
references/troubleshooting.md
```
- Common issues and solutions

更多模板和示例请查看

references/

部署相关：

references/deployment/docker-compose-production.yaml

- 生产环境Docker Compose配置

```
references/deployment/helm-values.yaml
```
- v4.x版本Helm配置（Chart v0.40.0）
```
references/deployment/helm-values-hyades.yaml
```
- Hyades v5.x版本Helm配置（Chart v0.10.0）

references/deployment/kubernetes-manifests/

- 原生Kubernetes清单

CI/CD集成相关：

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

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
```
- 常见问题与解决方案