Research Reports

Analyzing Dependency-Track

7 min read

Analyzing Dependency-Track

Source: DependencyTrack/dependency-track @ dc1241c

How It Works

Dependency-Track is an OWASP flagship platform for software supply chain risk analysis. It ingests Software Bill of Materials (SBOM) documents — primarily in CycloneDX format — and automatically correlates every listed component against known vulnerability databases, license policies, and operational risk criteria. Rather than scanning source code directly, it operates on SBOMs produced by build pipelines, making it ecosystem-agnostic: a single CycloneDX BOM from a Maven, npm, Python, or Cargo project flows through the same analysis pipeline.

The core workflow is event-driven. When a BOM is uploaded via the REST API, the system parses it, resolves component identities (using CPEs, Package URLs, and SWID tags), and fires asynchronous events for vulnerability analysis, policy evaluation, and metrics computation. Vulnerability intelligence is gathered from multiple upstream sources — NVD, GitHub Advisories, OSV, Snyk, Trivy, Sonatype OSS Index, and VulnDB — each mirrored or queried on a schedule. Components are matched against the aggregated vulnerability database, and findings are stored with attribution so operators know which scanner identified each issue.

Beyond vulnerability detection, Dependency-Track includes a policy engine that evaluates components against configurable rules covering severity thresholds, license compliance, component age, version currency, EPSS scores, and more. Violations trigger notifications through pluggable publishers (Slack, Teams, Jira, email, webhooks). The platform also tracks portfolio-level metrics, supports project cloning and versioning, and provides a comprehensive auditing workflow for triaging findings.

Architecture

Dependency-Track is a monolithic Java 21 web application (WAR packaging) built on the Alpine framework — a purpose-built foundation by the same author (Steve Springett) that provides persistence, authentication, event dispatch, and REST scaffolding. The frontend is a separate JavaScript application distributed independently. Key architectural layers:

  • Resources (resources/v1/): ~37 JAX-RS resource classes providing the REST API, documented with OpenAPI annotations. Each resource extends AlpineResource and enforces permissions via @PermissionRequired.
  • Persistence (persistence/): DataNucleus JDO with a QueryManager god-object (~1,700 lines) delegating to specialized query managers (BomQueryManager, VulnerabilityQueryManager, PolicyQueryManager, etc.). Supports PostgreSQL, MySQL, and MSSQL via configurable JDBC drivers; H2 for development.
  • Tasks (tasks/): Asynchronous event subscribers implementing Alpine’s Subscriber interface. Includes BOM processing, vulnerability mirroring (NVD, GitHub, OSV, VulnDB), policy evaluation, metrics aggregation, and integration uploads (Fortify SSC, DefectDojo, Kenna).
  • Scanners (tasks/scanners/): Pluggable vulnerability analysis tasks — InternalAnalysis, OSS Index, Snyk, Trivy, VulnDB — each extending BaseComponentAnalyzerTask and optionally implementing CacheableScanTask for result caching.
  • Parsers (parser/): Parsers for CycloneDX BOMs, NVD CVE data, OSV, GitHub Advisories, EPSS, SPDX license expressions, and Snyk vulnerability feeds.
  • Policy (policy/): Strategy-pattern policy engine with ~15 evaluators (severity, license, age, version distance, EPSS, CWE, etc.) registered at construction time.
  • Notification (notification/): Router that dispatches notifications to configured publishers based on rules matching scope, group, level, and project/tag filters.
  • Search (search/): Lucene-based indexing for components, projects, vulnerabilities, licenses, and services — used for full-text search across the portfolio.

The Spine

The request lifecycle for the most critical operation — BOM upload — reveals the system’s spine:

  1. HTTP entry: BomResource (JAX-RS) receives a POST with the BOM payload (base64-encoded or multipart). Validates the BOM format using CycloneDxValidator.
  2. Event dispatch: The resource creates a BomUploadEvent and publishes it via Event.dispatch(). Returns immediately to the caller with a processing token — BOM processing is fully asynchronous.
  3. BOM parsing: BomUploadProcessingTask subscribes to BomUploadEvent. Parses the BOM using the CycloneDX Java library, resolves component identities, and persists components to the database via QueryManager.
  4. Vulnerability analysis: Fires ProjectVulnerabilityAnalysisEvent, which triggers VulnerabilityAnalysisTask. This task runs each scanner (Internal, OSS Index, Snyk, Trivy) against every component, caching results in ComponentAnalysisCache.
  5. Policy evaluation: PolicyEvaluationEvent triggers PolicyEvaluationTask, which runs the PolicyEngine against all project components.
  6. Metrics and notifications: Metrics update events cascade (component → project → portfolio). Policy violations and new vulnerabilities trigger NotificationRouter dispatches to configured publishers.

The EventSubsystemInitializer servlet listener wires all event↔subscriber subscriptions at startup — a single class that serves as the wiring diagram for the entire async subsystem.

Key Patterns

Event-driven async processing. Nearly all heavy work is dispatched through Alpine’s EventService (multi-threaded) or SingleThreadedEventService (for indexing). Events are in-memory only — no persistent queue. This means a server restart loses in-flight events, which is a known operational consideration.

QueryManager as data access facade. A single QueryManager class serves as the gateway to all persistence, delegating to ~15 specialized managers. It wraps DataNucleus PersistenceManager lifecycle and provides transaction boundaries. The pattern is consistent: open QM in try-with-resources, perform operations, close.

Scanner strategy pattern. Vulnerability scanners implement a common interface (ScanTask, CacheableScanTask) and extend BaseComponentAnalyzerTask. Adding a new scanner means creating a task class, an event class, and registering the subscription in EventSubsystemInitializer.

Policy evaluator strategy. PolicyEngine constructs a list of PolicyEvaluator implementations at startup. Each evaluator handles one condition type (severity, license, age, etc.). New policy types require adding an evaluator class and registering it in the constructor.

Repository meta-analysis. Each supported package ecosystem (Maven, npm, PyPI, etc.) has an IMetaAnalyzer implementation that queries the public repository for latest version and published date — used for version distance and component age policies.

Non-Obvious Details

No persistent event queue. Alpine’s EventService is an in-memory thread pool. If the server crashes mid-BOM-processing, that work is lost. The caller can poll an “is token being processed” endpoint, but there’s no replay mechanism. For production deployments, this means BOM uploads should be treated as at-least-once operations.

QueryManager is 1,700+ lines. The persistence layer funnels through a single god-class that delegates to ~15 sub-managers. While the delegation pattern is clean, the QueryManager itself handles cross-cutting concerns (notifications, metrics updates) that don’t belong in a data access layer.

BOM processing uses a ReentrantLock per project. BomUploadProcessingTask acquires a lock keyed by project UUID before processing, preventing concurrent BOM uploads for the same project from corrupting data. This is a sensible guard but means BOM uploads for the same project are serialized.

The alpine-parent POM is the foundation — it controls dependency versions, plugin configuration, and build lifecycle. Understanding Alpine is essential to understanding Dependency-Track. The parent framework provides auth (LDAP, OIDC, API keys), the event system, notification infrastructure, and the JAX-RS resource base class.

Component analysis cache prevents redundant scans. CacheableScanTask implementations check a time-bounded cache before querying external scanners. This is critical for performance — without it, every BOM upload would re-query NVD, OSS Index, and Snyk for every component.

Lucene indexes live alongside the database. Full-text search uses Lucene indexes managed by IndexManager, not database queries. IndexTask runs on the single-threaded event service to avoid concurrent index corruption. Indexes are rebuilt on startup if missing.

Assessment

Strengths:

  • Mature, production-grade platform. OWASP flagship project with 10+ years of development, extensive test coverage, and real-world deployment at scale.
  • Comprehensive vulnerability intelligence. Integrates with every major vulnerability database (NVD, GitHub, OSV, Snyk, Trivy, VulnDB, OSS Index) out of the box.
  • Well-designed policy engine. The evaluator strategy pattern makes it straightforward to add new policy types. The range of built-in evaluators (severity, EPSS, age, license, version distance) covers most real-world governance needs.
  • API-first design. Every feature is exposed via well-documented REST endpoints with OpenAPI specs, making CI/CD integration natural.
  • Ecosystem-agnostic. By operating on SBOMs rather than scanning code, it works with any language or package manager that can produce a CycloneDX BOM.

Concerns:

  • In-memory event system. No persistent queue means in-flight work is lost on restart. For a platform that processes potentially large BOMs in production, this is a meaningful reliability gap.
  • Monolithic persistence layer. The QueryManager god-class at 1,700+ lines is the single biggest maintainability risk. Cross-cutting concerns (notifications triggered from data access) make it hard to test in isolation.
  • Tight coupling to Alpine. The framework provides essential infrastructure but also creates a hard dependency. Migrating to a more mainstream stack (Spring, Quarkus) would be extremely costly, and Alpine’s community is tiny by comparison.
  • Single-threaded indexing. Lucene indexing runs on a single-threaded event service, which can become a bottleneck for large portfolios.

For organizations adopting Dependency-Track, the API-first design is the key integration point. Focus on automating CycloneDX BOM generation in your CI/CD pipeline and uploading to Dependency-Track as a build step rather than trying to use the UI as the primary interface.

Graph View

Backlinks