Dependency Track

Dependency-Track Skill

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

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

Quick Reference

1. Deployment Options

Docker Compose (Recommended for Production)

# 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

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

Kubernetes with Helm

# 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

Available Charts:

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

ArgoCD GitOps Deployment (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
      example-app-dev/
        values.yaml             # Environment-specific Helm values
        secretproviderclass.yaml # Azure Key Vault CSI integration

ApplicationSet Example (Multi-Source):

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

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:

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.

Hyades (Next-Generation Architecture)

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+

# 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"

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

2. Initial Configuration

First-Time Setup

1. 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

2. Change default password immediately after first login

3. Enable analyzers in Administration > Analyzers:

   • Internal Analyzer (built-in)
   • OSS Index (requires API token from ossindex.sonatype.org)
   • Snyk (optional, requires token)
   • Trivy (optional)

Database Configuration (Production)

# 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=%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}))

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

How OIDC Groups Work in Dependency-Track

1. 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

2. 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

Method 1: API-Based Setup (Recommended)

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

# 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: The /api/v1/oidc/mapping endpoint expects UUID strings, not objects. Using {"team": {"uuid": "..."}, "group": {"uuid": "..."}} will return HTTP 400.

Verifying OIDC Group Mappings

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

# 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 Output (example-app-dev cluster):

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

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

Method 2: Manual UI Configuration

1. Create Teams:

   • Go to Administration > Access Management > Teams
   • Create teams: Administrators, Moderators, Auditors, Developers
   • Assign permissions to each team

2. Map Groups:

   • Go to Administration > Access Management > OpenID Connect Groups
   • Click "Create Group"
   • Enter Azure AD Group Object ID (e.g., <AAD_GROUP_ID_ADMIN>)
   • Select Team to map to
   • Save

Retrieving Azure AD Group Object IDs

# 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

Validating Group Claims in ID Token

1. 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

2. 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

Environment Variables Reference

3. CI/CD Integration

Workflow: BOM Upload Pipeline

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

Jenkins Pipeline

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

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

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 Pipeline

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 Usage

Authentication

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

# 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 Specification

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

Common API Operations

# 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 "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

Policy Types

Creating Policies via 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\"}"
         }
       ]
     }'

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

6. Notifications & Integrations

Webhook Configuration

{
  "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

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

7. SBOM Generation Tools

By Language/Ecosystem

Universal Tools

# 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. Best Practices

Deployment

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

Operations

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

Security

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

Performance

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

9. Troubleshooting

Common Issues

Debug Commands

# 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"

Performance Tuning

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

10. Reference Files

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

Related Skills

• defectdojo-skill - Vulnerability management integration
• argocd-skill - GitOps deployment of Dependency-Track
• quality-guardian - Security testing integration

Gotchas

• BOM upload without projectVersion overwrites the previous BOM: Uploading to the same project name without a distinct version replaces the inventory instead of versioning it. Always pass projectVersion (commit SHA or semver) and consider parentName/parentVersion for monorepos.
• OSS Index analyzer runs on a 6-hour schedule, not on upload: A fresh SBOM may show zero vulnerabilities for hours because the analyzer hasn't swept it yet. Re-upload the BOM or wait — don't conclude "clean" from the immediate UI state.
• /api/v1/oidc/mapping expects UUID strings, not objects: Sending {"team": {"uuid": "..."}, "group": {"uuid": "..."}} returns 400. Use {"team": "<uuid>", "group": "<uuid>"}. OIDC groups only appear in the UI after a user from that group logs in once.
• First-time startup mirrors NVD for 10-30+ minutes: During this window the API works but vulnerability matching is incomplete. Do not benchmark, do not ship pipeline integration until logs show NVD mirror complete — early scans look falsely clean.
• API server needs 4.5GB RAM minimum: Below that the JVM OOMs mid-mirror leaving a half-initialized database. Recovery often requires wiping /data and restarting. Set Helm apiServer.resources.requests.memory accordingly before scaling.
• NGINX Ingress default body size rejects large SBOMs as 413: Monorepo or container BOMs frequently exceed 1MB. Add nginx.ingress.kubernetes.io/proxy-body-size: "100m" to the ingress annotations.