mcpField
D
dependency-track-skill

dependency-track-skill

github.com/julianobarbosaセキュリティ1452 回インストール2 日前に更新
リポジトリ

dependency-track-skill について

dependency-track-skillは、SBOMベースのソフトウェア構成分析プラットフォームDependency-Trackの導入と運用を案内するスキルです。デプロイ、設定、CI/CDの手順を扱い、ソフトウェアサプライチェーンのリスク管理に役立ちます。

主な機能

  1. 01Docker Compose、Helm、ArgoCDのデプロイ手順
  2. 02CycloneDX SBOMとVEXの管理
  3. 03脆弱性・コンプライアンスポリシー設定
  4. 04OIDC、LDAP、チームマッピング
  5. 05CI/CDのアップロードとスキャン例

活用シーン

  1. 01KubernetesへのDependency-Track導入
  2. 02OIDCのチームアクセスマッピング設定
  3. 03CI/CDへのSBOMアップロード工程の追加

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/julianobarbosa/claude-code-skills --skill dependency-track-skill

インストール後、Claude Code で/dependency-track-skillを入力して読み込まれたか確認します。

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

references/
azure-ad-validation.md
troubleshooting.md
references/api/
python-client.py
references/api/bash-scripts/
manage-projects.sh
security-gate.sh
upload-sbom.sh
references/cicd/
azure-pipeline.yaml
github-action.yaml
gitlab-ci.yaml
jenkinsfile
references/deployment/
docker-compose-production.yaml
helm-values-hyades.yaml
helm-values.yaml
references/policies/
license-policies.json
operational-policies.json
security-policies.json

詳細

Dependency-Track スキル

Dependency-Track を実装、デプロイ、運用するための包括的なガイドです。SBOM 管理を通じてソフトウェアサプライチェーンのリスクを特定し、低減するインテリジェントなソフトウェア構成分析（SCA）プラットフォームです。

現在のバージョン：

  • Helm Chart：0.40.0
  • アプリケーションバージョン：4.13.6
  • Helm リポジトリ：https://dependencytrack.github.io/helm-charts

概要

Dependency-Track は API ファーストのプラットフォームで、次の機能を備えています。

  • CycloneDX SBOM と VEX ドキュメントを取り込み、生成します
  • ポートフォリオ全体で既知の脆弱性についてコンポーネントを監視します
  • NVD、GitHub Advisories、OSS Index、Snyk、Trivy、OSV、VulnDB と連携します
  • セキュリティ、ライセンス、運用コンプライアンスのポリシー適用機能を提供します
  • OAuth 2.0、OIDC、LDAP、Active Directory 認証に対応します
  • 優先順位付けに EPSS（Exploit Prediction Scoring System）をサポートします
  • API と外部サービスのコンポーネントを特定します

クイックリファレンス

リソースパス
デプロイテンプレートreferences/deployment/
CI/CD 連携references/cicd/
API の例references/api/
ポリシーテンプレートreferences/policies/
トラブルシューティングreferences/troubleshooting.md

1. デプロイオプション

Docker Compose（本番環境に推奨）
# Download official docker-compose
curl -LO https://dependencytrack.org/docker-compose.yml

# Start services
docker compose up -d

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

最小要件：

  • API サーバー：4.5GB RAM、2 CPU コア
  • フロントエンド：512MB RAM、1 CPU コア

推奨要件：

  • API サーバー：16GB RAM、4 CPU コア
  • フロントエンド：1GB RAM、2 CPU コア
Helm を使用した Kubernetes
# Add Helm repository
helm repo add dependency-track https://dependencytrack.github.io/helm-charts
helm repo update

# View available charts
helm search repo dependency-track

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

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

利用可能なチャート：

チャート説明ステータス
dependency-track/dependency-trackモノリシックデプロイ（v4.x）本番環境で利用可能
dependency-track/hyadesマイクロサービスデプロイ（v5.x）インキュベーション中（GA 前）

マニフェストと Helm の値の全容については、references/deployment/ を参照してください。

ArgoCD GitOps デプロイ（AKS）

複数のソースを使用する ApplicationSet で ArgoCD を利用する、エンタープライズ向け Kubernetes デプロイの場合：

ディレクトリ構成：

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

ApplicationSet の例（複数ソース）：

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

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 の許容設定（コスト最適化）：

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

ArgoCD の主な ignoreDifferences 設定：

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

ApplicationSet と値の例の全容については、references/deployment/argocd/ を参照してください。

Hyades（次世代アーキテクチャ）

Hyades は Dependency-Track v5 のインキュベーション中のプロジェクトで、モノリシックな API サーバーを、個別にスケーリング可能なマイクロサービスに分割します。

コンポーネント：

  • hyades-apiserver - コア API サーバー
  • hyades-frontend - Web UI
  • hyades-notification-publisher - 通知処理
  • hyades-repository-meta-analyzer - リポジトリのメタデータ分析
  • hyades-vulnerability-analyzer - 脆弱性スキャン

要件：

  • 外部 PostgreSQL データベース
  • Apache Kafka クラスター
  • Kubernetes 1.19+
# Install Hyades (NOT PRODUCTION READY)
helm install hyades dependency-track/hyades \
    --namespace dtrack \
    --create-namespace \
    --set common.database.jdbcUrl="jdbc:postgresql://postgres:5432/dtrack" \
    --set common.database.username="dtrack" \
    --set common.database.password="secret" \
    --set common.kafka.bootstrapServers="kafka:9092"

警告： Hyades は一般提供されていません。予告なく破壊的変更が行われる可能性があります。テスト環境でのみ使用してください。GA ロードマップ：https://github.com/DependencyTrack/hyades/issues/860

2. 初期設定

初回セットアップ

  1. 初期化を待ちます（10～30 分以上）：

    • デフォルトユーザー、チーム、権限を作成します
    • NVD、GitHub Advisories をミラーリングします（中断しないでください）
    • 進捗状況を確認します：docker logs -f dependency-track-apiserver

  2. 初回ログイン後、すぐにデフォルトのパスワードを変更します

  3. Administration > Analyzers でアナライザーを有効化します：

    • Internal Analyzer（組み込み）
    • OSS Index（ossindex.sonatype.org の API トークンが必要）
    • Snyk（任意。トークンが必要）
    • Trivy（任意）
データベース設定（本番環境）
# docker-compose override for PostgreSQL
services:
  apiserver:
    environment:
      ALPINE_DATABASE_MODE: external
      ALPINE_DATABASE_URL: jdbc:postgresql://postgres:5432/dtrack
      ALPINE_DATABASE_DRIVER: org.postgresql.Driver
      ALPINE_DATABASE_USERNAME: dtrack
      ALPINE_DATABASE_PASSWORD: ${DB_PASSWORD}
LDAP/Active Directory
# Active Directory configuration
ALPINE_LDAP_ENABLED=true
ALPINE_LDAP_SERVER_URL=ldap://ldap.example.com:3268
ALPINE_LDAP_BASEDN=dc=example,dc=com
ALPINE_LDAP_SECURITY_AUTH=simple
ALPINE_LDAP_AUTH_USERNAME_FORMAT=%[email protected]
ALPINE_LDAP_ATTRIBUTE_NAME=userPrincipalName
ALPINE_LDAP_ATTRIBUTE_MAIL=mail
ALPINE_LDAP_GROUPS_FILTER=(&(objectClass=group)(objectCategory=Group))
ALPINE_LDAP_USER_GROUPS_FILTER=(&(objectClass=group)(member:1.2.840.113556.1.4.1941:={USER_DN}))
OpenID Connect（Azure AD、Okta、Keycloak）
ALPINE_OIDC_ENABLED=true
ALPINE_OIDC_ISSUER=https://login.microsoftonline.com/{tenant}/v2.0
ALPINE_OIDC_CLIENT_ID=your-client-id
ALPINE_OIDC_USERNAME_CLAIM=preferred_username
ALPINE_OIDC_TEAMS_CLAIM=groups
ALPINE_OIDC_USER_PROVISIONING=true
ALPINE_OIDC_TEAM_SYNCHRONIZATION=true
Azure AD OIDC グループ連携（詳細ガイド）
Dependency-Track における OIDC グループの仕組み

  1. グループクレームのフロー：

    • ユーザーが Azure AD を通じて認証します
    • Azure AD は groups クレーム（グループのオブジェクト ID の配列）を含む ID トークンを返します
    • Dependency-Track は groups クレームを読み取ります（ALPINE_OIDC_TEAMS_CLAIM で設定）
    • OpenID Connect グループマッピングを通じて、グループがチームに紐付けられます

  2. 重要な動作：

    • Administration > OpenID Connect Groups にグループが表示されるのは、そのグループに所属するユーザーが認証した後のみです
    • グループマッピングの前にチームが存在している必要があります（ALPINE_OIDC_TEAM_SYNCHRONIZATION=true の場合は自動作成されます）
    • 表示名ではなく、グループのオブジェクト ID（UUID）が使用されます
方法 1：API による設定（推奨）

REST API を使用して、チーム、OIDC グループ、マッピングを作成します。

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

# Azure AD Group Object ID
AZURE_GROUP_ID="31d6daa5-5cc2-4e5f-9bf5-75ee8e09198c"

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

重要： /api/v1/oidc/mapping エンドポイントが想定しているのは、オブジェクトではなく UUID 文字列です。 {"team": {"uuid": "..."}, "group": {"uuid": "..."}} を使用すると、HTTP 400 が返されます。

OIDC グループマッピングの確認

次のコマンドを使用して、OIDC グループがチームに正しくマッピングされていることを確認します。

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

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

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

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

出力例（cafehyna-dev クラスター）：

[
  {"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）を使用してください。

方法 2：UI による手動設定

  1. チームを作成する：

    • Administration > Access Management > Teams に移動します
    • チームを作成します：Administrators、Moderators、Auditors、Developers
    • 各チームに権限を割り当てます

  2. グループをマッピングする：

    • Administration > Access Management > OpenID Connect Groups に移動します
    • 「Create Group」をクリックします
    • Azure AD グループのオブジェクト ID（例：31d6daa5-5cc2-4e5f-9bf5-75ee8e09198c）を入力します
    • マッピング先のチームを選択します
    • 保存します
Azure AD グループのオブジェクト ID の取得
# List all Azure AD groups with DependencyTrack in name
az ad group list --filter "startswith(displayName, 'G-Usuarios-DependencyTrack')" \
  --query "[].{name:displayName, id:id}" -o table

# Get specific group Object ID
az ad group show --group "G-Usuarios-DependencyTrack-Admin" --query id -o tsv
ID トークンのグループクレームの検証

  1. JWT トークンをデコードする（jwt.io を使用）：

    • Dependency-Track にログインします
    • /api/v1/oidc/callback へのネットワークリクエストを取得します
    • id_token をデコードし、groups クレームに想定される UUID が含まれていることを確認します

  2. Azure AD トークン設定のチェックリスト：

    • アプリ登録で groupMembershipClaims: SecurityGroup が設定されている
    • オプションのクレームで ID トークンに groups が含まれている
    • API のアクセス許可：GroupMember.Read.All（委任）
    • 管理者の同意が付与されている
環境変数のリファレンス
変数説明例
ALPINE_OIDC_ENABLEDOIDC を有効化true
ALPINE_OIDC_ISSUERAzure AD 発行者 URLhttps://login.microsoftonline.com/{tenant}/v2.0
ALPINE_OIDC_CLIENT_IDアプリ登録のクライアント IDKey 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 連携

ワークフロー：BOM アップロードパイプライン
┌─────────────┐     ┌─────────────┐     ┌──────────────────┐
│   Build     │────▶│ Generate    │────▶│    Upload to     │
│   Project   │     │ CycloneDX   │     │ Dependency-Track │
└─────────────┘     │    SBOM     │     └──────────────────┘
                    └─────────────┘              │
                                                 ▼
                    ┌─────────────┐     ┌──────────────────┐
                    │   Break     │◀────│    Evaluate      │
                    │   Build?    │     │    Policies      │
                    └─────────────┘     └──────────────────┘
Jenkins パイプライン
pipeline {
    agent any

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

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

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

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

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

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

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

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

公式 GitHub Action のオプション（DependencyTrack/gh-upload-sbom@v3）：

パラメーター必須デフォルト説明
serverHostnameはい-Dependency-Track サーバーの URL
apiKeyはい-BOM_UPLOAD 権限を持つ API キー
projectNameはい-プロジェクト名
projectVersionはい-プロジェクトのバージョン
bomFilenameはい-CycloneDX SBOM ファイルのパス
autoCreateいいえfalseプロジェクトが存在しない場合に自動作成
parentNameいいえ-親プロジェクト名
parentVersionいいえ-親プロジェクトのバージョン
projectUuidいいえ-名前／バージョンの代わりに UUID を使用
GitLab CI
stages:
  - build
  - security

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

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

pool:
  vmImage: 'ubuntu-latest'

variables:
  - group: dependency-track-credentials

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

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

4. REST API の使用

認証

Administration > Access Management > Teams > [Team] > API Keys で API キーを生成します。

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

アクセス先：

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

注記： ポート 8080（フロントエンド）ではなく、ポート 8081（API サーバー）を使用してください。

一般的な API 操作
# List all projects
curl -s -H "X-Api-Key: ${API_KEY}" \
     "${DTRACK_URL}/api/v1/project" | jq

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

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

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

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

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

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

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

5. ポリシー設定

ポリシーの種類
種類目的条件の例
License許可または禁止するライセンスを制御しますApache-2.0 は許可、GPL-3.0 は禁止
Security脆弱性の深刻度のしきい値を設定しますCritical は不可、High は最大 5 件
Operationalコンポーネントの許可リスト／拒否リストを設定しますlog4j < 2.17.0 をブロック
API によるポリシーの作成
# Create a security policy
curl -X PUT "${DTRACK_URL}/api/v1/policy" \
     -H "X-Api-Key: ${API_KEY}" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "No Critical Vulnerabilities",
       "operator": "ANY",
       "violationState": "FAIL",
       "policyConditions": [
         {
           "subject": "SEVERITY",
           "operator": "IS",
           "value": "CRITICAL"
         }
       ]
     }'

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

# Create operational policy (block specific component)
curl -X PUT "${DTRACK_URL}/api/v1/policy" \
     -H "X-Api-Key: ${API_KEY}" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "Block Vulnerable Log4j",
       "operator": "ALL",
       "violationState": "FAIL",
       "policyConditions": [
         {
           "subject": "COORDINATES",
           "operator": "MATCHES",
           "value": "{\"group\":\"org.apache.logging.log4j\",\"name\":\"log4j-core\",\"version\":\"<2.17.0\"}"
         }
       ]
     }'
ポリシー条件の対象
  • AGE - コンポーネントの経過期間
  • COORDINATES - グループ／名前／バージョン
  • CPE - Common Platform Enumeration
  • CWE - Common Weakness Enumeration
  • EPSS - Exploit Prediction Scoring System
  • LICENSE - 特定のライセンス
  • LICENSE_GROUP - ライセンスの分類
  • PACKAGE_URL - Package URL（PURL）
  • SEVERITY - 脆弱性の深刻度
  • SWID_TAGID - ソフトウェア ID タグ
  • VERSION - コンポーネントのバージョン
  • COMPONENT_HASH - MD5、SHA、Blake ハッシュ

6. 通知と連携

Webhook の設定
{
  "notification": {
    "level": "INFORMATIONAL",
    "scope": "PORTFOLIO",
    "group": "NEW_VULNERABILITY",
    "timestamp": "2024-01-15T10:30:00Z",
    "subject": {
      "component": {
        "name": "log4j-core",
        "version": "2.14.1"
      },
      "vulnerability": {
        "vulnId": "CVE-2021-44228",
        "severity": "CRITICAL"
      },
      "affectedProjects": [...]
    }
  }
}
通知グループ
  • NEW_VULNERABILITY - 新しい脆弱性を特定
  • NEW_VULNERABLE_DEPENDENCY - 新しい脆弱なコンポーネントを追加
  • ANALYSIS_DECISION_CHANGE - 監査の判定を変更
  • POLICY_VIOLATION - ポリシー違反を検出
  • BOM_CONSUMED - SBOM を処理
  • BOM_PROCESSED - SBOM の分析が完了
  • VEX_CONSUMED - VEX ドキュメントを処理
連携先
  • Slack/Teams：Webhook に直接対応
  • Email：SMTP の設定
  • Jira：ネイティブ連携
  • DefectDojo：脆弱性の集約
  • Fortify SSC：AppSec プラットフォーム
  • ThreadFix：脆弱性管理
  • Kenna Security：リスクの優先順位付け

7. SBOM 生成ツール

言語／エコシステム別
言語ツールコマンド
Java/Mavencyclonedx-maven-pluginmvn org.cyclonedx:cyclonedx-maven-plugin:makeAggregateBom
Java/Gradlecyclonedx-gradle-plugingradle cyclonedxBom
Node.js@cyclonedx/cyclonedx-npmnpx @cyclonedx/cyclonedx-npm --output-file bom.json
Pythoncyclonedx-pycyclonedx-py -r requirements.txt -o bom.json
Gocyclonedx-gomodcyclonedx-gomod mod -json -output bom.json
.NETCycloneDXdotnet CycloneDX <project> -o bom.json
Rustcargo-cyclonedxcargo cyclonedx -f json
ContainerSyftsyft <image> -o cyclonedx-json > bom.json
汎用ツール
# Syft - multi-ecosystem SBOM generator
syft packages dir:. -o cyclonedx-json > bom.json

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

# cdxgen - comprehensive generator
cdxgen -o bom.json

8. ベストプラクティス

デプロイ
  1. 本番環境では外部 PostgreSQL を使用する（組み込み H2 ではなく）
  2. 十分な RAM を割り当てる（API サーバーには最低 4.5GB）
  3. /data ディレクトリに永続ストレージを設定する
  4. 適切な証明書を使用して TLS を有効にする
  5. データベースと設定の定期バックアップを設定する
運用
  1. CI/CD で SBOM を生成する - ビルド時に自動化します
  2. OSS Index Analyzer を有効にする - PURL ベースのスキャンに必要です
  3. NVD をローカルにミラーリングする - パフォーマンスが向上します
  4. パイプラインでは同期アップロードを使用する - すぐにフィードバックを得られます
  5. ポリシーゲートを実装する - 違反時にビルドを失敗させます
セキュリティ
  1. API キーを定期的にローテーションする
  2. 最小限の権限を持つチームスコープのキーを使用する
  3. コンプライアンスのために監査ログを有効にする
  4. エンタープライズ認証用に OIDC/LDAP を設定する
  5. ベンダーに SBOM の提供を契約上義務付ける
パフォーマンス
  1. 負荷の高い処理は営業時間外にスケジュールする
  2. 大きな API レスポンスにはページネーションを使用する
  3. 頻繁にアクセスするデータにキャッシュを実装する
  4. アナライザーキューの深さを監視する
  5. 複数の API サーバーレプリカで水平スケールする

9. トラブルシューティング

よくある問題
問題原因解決策
脆弱性が見つからないOSS Index が有効になっていないAdmin > Analyzers で有効にし、API トークンを取得します
アナライザーが実行されない6 時間ごとのスケジュールSBOM を再アップロードするか、スケジュールされた実行を待ちます
コンテナーがクラッシュするRAM 不足API サーバーに最低 4.5GB を割り当てます
413 Request Entity Too LargeNginx のボディサイズ制限nginx.ingress.kubernetes.io/proxy-body-size: "100m" を追加します
PKIX path building error自己署名証明書設定で内部 CA を構成します
LDAP 同期の遅延非同期ジョブキュー待機するか、アカウントを手動で作成します
1～2 週間後にサービスが停止するOS による一時ファイルのクリーンアップ-Djava.io.tmpdir=/path/to/tmpdir を設定します
デバッグコマンド
# Check API server logs
docker logs -f dependency-track-apiserver

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

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

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

# Health check
curl -s "${DTRACK_URL}/api/version"
パフォーマンスのチューニング
# JVM settings for high-load environments
environment:
  JAVA_OPTIONS: >-
    -Xms8g
    -Xmx16g
    -XX:+UseG1GC
    -XX:MaxGCPauseMillis=200
    -XX:+ParallelRefProcEnabled

10. 参照ファイル

追加のテンプレートと例は references/ ディレクトリにあります。

デプロイメント：

  • references/deployment/docker-compose-production.yaml - 本番環境用の Docker Compose
  • references/deployment/helm-values.yaml - v4.x 用の Helm 値（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 Pipeline の例
  • references/cicd/github-action.yaml - GitHub Actions のワークフロー
  • references/cicd/gitlab-ci.yaml - GitLab CI/CD パイプライン
  • references/cicd/azure-pipeline.yaml - Azure DevOps Pipeline

API とスクリプト：

  • references/api/python-client.py - Python クライアントライブラリの例
  • references/api/bash-scripts/ - 一般的な操作用のシェルスクリプト

ポリシー：

  • references/policies/security-policies.json - セキュリティポリシーのテンプレート
  • references/policies/license-policies.json - ライセンスポリシーのテンプレート
  • references/policies/operational-policies.json - 運用ポリシーのテンプレート

トラブルシューティング：

  • references/troubleshooting.md - よくある問題と解決策

関連スキル

  • defectdojo-skill - 脆弱性管理との統合
  • argocd-skill - Dependency-Track の GitOps デプロイメント
  • quality-guardian - セキュリティテストとの統合

コメント

Markdown 対応