dependency-track
Comprehensive guide for Dependency-Track - Software Composition Analysis (SCA) and SBOM management platform. USE WHEN deploying Dependency-Track, integrating with CI/CD pipelines, configuring vulnerability scanning, managing SBOMs, setting up policy compliance, troubleshooting installation issues, or working with the REST API.
How do I install this agent skill?
npx skills add https://github.com/julianobarbosa/claude-code-skills --skill dependency-trackIs this agent skill safe to install?
- Gen Agent Trust Hubpass
This skill is a comprehensive guide and set of utility scripts for Dependency-Track, an SCA platform. It follows security best practices, using environment variables for sensitive credentials and referencing official, well-known project resources for downloads and integrations. No malicious patterns or security risks were identified.
- Socketwarn
1 alert: gptAnomaly
- Snykpass
Risk: LOW · No issues
What does this agent skill do?
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
| Resource | Path |
|---|---|
| Deployment Templates | references/deployment/ |
| CI/CD Integration | references/cicd/ |
| API Examples | references/api/ |
| Policy Templates | references/policies/ |
| Troubleshooting | references/troubleshooting.md |
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:
| 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.
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 serverhyades-frontend- Web UIhyades-notification-publisher- Notification handlinghyades-repository-meta-analyzer- Repository metadata analysishyades-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
-
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)
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
-
Group Claim Flow:
- User authenticates via Azure AD
- Azure AD returns ID token with
groupsclaim (array of Group Object IDs) - Dependency-Track reads the
groupsclaim (configured viaALPINE_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
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/mappingendpoint 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
-
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.,
<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
-
Decode JWT Token (use jwt.io):
- Login to Dependency-Track
- Capture network request to
/api/v1/oidc/callback - Decode the
id_tokento verifygroupsclaim contains expected UUIDs
-
Azure AD Token Configuration Checklist:
- App Registration has
groupMembershipClaims: SecurityGroup - Optional Claims include
groupsin ID Token - API Permissions:
GroupMember.Read.All(delegated) - Admin consent granted
- App Registration has
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 |
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):
| 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 |
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
| 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 |
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 ageCOORDINATES- Group/Name/VersionCPE- Common Platform EnumerationCWE- Common Weakness EnumerationEPSS- Exploit Prediction Scoring SystemLICENSE- Specific licenseLICENSE_GROUP- License categoryPACKAGE_URL- Package URL (PURL)SEVERITY- Vulnerability severitySWID_TAGID- Software ID tagVERSION- Component versionCOMPONENT_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 identifiedNEW_VULNERABLE_DEPENDENCY- New vulnerable component addedANALYSIS_DECISION_CHANGE- Audit decision modifiedPOLICY_VIOLATION- Policy violation detectedBOM_CONSUMED- SBOM processedBOM_PROCESSED- SBOM analysis completeVEX_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
| 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 |
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
- Use external PostgreSQL for production (not embedded H2)
- Allocate sufficient RAM (minimum 4.5GB for API server)
- Configure persistent storage for
/datadirectory - Enable TLS with proper certificates
- Set up regular backups of database and configuration
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
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
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
9. Troubleshooting
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 |
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 productionreferences/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 examplereferences/cicd/github-action.yaml- GitHub Actions workflowreferences/cicd/gitlab-ci.yaml- GitLab CI/CD pipelinereferences/cicd/azure-pipeline.yaml- Azure DevOps Pipeline
API & Scripts:
references/api/python-client.py- Python client library examplereferences/api/bash-scripts/- Shell scripts for common operations
Policies:
references/policies/security-policies.json- Security policy templatesreferences/policies/license-policies.json- License policy templatesreferences/policies/operational-policies.json- Operational policy templates
Troubleshooting:
references/troubleshooting.md- Common issues and solutions
Related Skills
defectdojo-skill- Vulnerability management integrationargocd-skill- GitOps deployment of Dependency-Trackquality-guardian- Security testing integration
Gotchas
- BOM upload without
projectVersionoverwrites the previous BOM: Uploading to the same project name without a distinct version replaces the inventory instead of versioning it. Always passprojectVersion(commit SHA or semver) and considerparentName/parentVersionfor 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/mappingexpects 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
/dataand restarting. Set HelmapiServer.resources.requests.memoryaccordingly 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.
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/julianobarbosa/claude-code-skills/dependency-track">View dependency-track on skillZs</a>