Skip to content

Expose direct vs. transitive dependency distinction in SBOM export APIs

Everyone can contribute. Help move this issue forward while earning points, leveling up and collecting rewards.

Problem to solve

Organizations need to distinguish between direct and transitive dependencies when exporting SBOM data for compliance purposes, particularly for European SBOM regulations that initially focus on direct dependencies only. While GitLab now tracks this information internally (as of #520809 (closed)), it's not clearly exposed through the SBOM export APIs or GraphQL queries in a way that enables compliance workflows.

Customer Use Case: A customer needs to export their project's SBOM to an external compliance tool that requires them to:

  1. Initially focus on securing/documenting direct dependencies only
  2. Gradually expand to full transitive dependency coverage
  3. Programmatically filter and process dependencies based on whether they are direct or transitive

Currently, when using the GraphQL API with the dependencyPaths field or the SBOM export endpoints, the distinction between direct and transitive dependencies is not clearly indicated in the response, making it impossible to filter or process them separately for compliance workflows.

Intended users

User experience goal

Users should be able to:

  1. Export SBOM data via API (GraphQL or REST) with a clear indicator of whether each dependency is direct or transitive
  2. Filter dependencies by type (direct/transitive) in API queries
  3. Integrate GitLab SBOM data with external compliance tools that require this distinction
  4. Meet regulatory requirements that mandate different treatment of direct vs. transitive dependencies

Proposal

Enhance the SBOM export capabilities to clearly expose the direct/transitive distinction:

Option 1: GraphQL API Enhancement

Add a boolean field isDirect to the dependency objects returned by GraphQL queries:

query GetDependenciesWithType {
  project(fullPath: "namespace/project") {
    dependencies {
      nodes {
        name
        version
        packager
        isDirect          # NEW FIELD
        isTransitive      # NEW FIELD (inverse of isDirect)
        dependencyPaths {
          nodes {
            isCyclic
            path { name version }
          }
        }
      }
    }
  }
}

Option 2: SBOM Export Format Enhancement

Enhance the CycloneDX SBOM export to include dependency scope or relationship information that clearly indicates direct vs. transitive:

{
  "components": [
    {
      "name": "example-package",
      "version": "1.0.0",
      "scope": "required",
      "properties": [
        {
          "name": "gitlab:dependency:type",
          "value": "direct"
        }
      ]
    }
  ]
}

Option 3: New API Filter Parameter

Add filter parameters to existing SBOM/dependency APIs:

GET /api/v4/projects/:id/dependencies?dependency_type=direct
GET /api/v4/projects/:id/dependencies?dependency_type=transitive
GET /api/v4/projects/:id/dependencies?dependency_type=all

Implementation Details

Based on the SBOM dependency graph ingestion documentation:

  • When a dependency is a direct dependency, the corresponding Sbom::Occurrence#ancestors contains an empty hash {}
  • When a dependency is transitive, the corresponding Sbom::Occurrence#ancestors contains entries
  • Dependencies can be both direct and transitive

The implementation should:

  1. Leverage the existing Sbom::Occurrence#ancestors data to determine if a dependency is direct
  2. Expose this information through all SBOM export mechanisms (GraphQL, REST API, file exports)
  3. Handle cases where a dependency is both direct and transitive (should be marked as direct)
  4. Ensure consistency across all package managers that support dependency graph tracking

Benefits

  1. Compliance Support: Enables organizations to meet regulatory requirements (e.g., European SBOM regulations) that differentiate between direct and transitive dependencies
  2. Risk Prioritization: Allows security teams to prioritize remediation of direct dependencies first
  3. Tool Integration: Enables seamless integration with external compliance and security tools
  4. Gradual Adoption: Supports phased compliance approaches that start with direct dependencies
  5. Transparency: Provides clear visibility into the dependency structure for audit purposes

Further details

Related Issues:

  • #520809 (closed) - Update parsers to return direct dependencies (closed - addressed internal tracking)
  • #525558 - Encode dependency capability map in SBOM (open - related to capability signaling)
  • Epic #16886 (closed) - Use explicit direct dependencies for dependency graph

Package Manager Support: According to #520809 (closed), the following package managers now support direct dependency tracking:

  • npm ✅
  • pnpm ✅
  • yarn classic ✅
  • Python (pip, pipenv, poetry, uv) ✅
  • Maven ✅
  • Gradle ✅
  • And others

Customer Context:

  • Customer is on Self-Managed Ultimate
  • Using npm/JavaScript projects
  • Needs this for European SBOM compliance requirements
  • Currently blocked from meeting compliance deadlines

Permissions and Security

No changes to permissions model. This feature exposes existing dependency relationship data through APIs in a more structured way.

Documentation

Documentation updates needed:

  • GraphQL API documentation for new fields
  • SBOM export format documentation
  • Dependency scanning documentation with compliance use case examples
  • API reference for new filter parameters

Availability & Testing

  • Should be available for all tiers that have dependency scanning (Ultimate)
  • Should work for all package managers that support dependency graph tracking
  • Test cases should cover:
    • Dependencies that are only direct
    • Dependencies that are only transitive
    • Dependencies that are both direct and transitive
    • API filtering and querying
    • SBOM export format validation

What does success look like, and how can we measure that?

Success Metrics:

  1. Users can successfully export SBOM data with direct/transitive indicators
  2. External compliance tools can consume GitLab SBOM exports with dependency type information
  3. Reduction in support tickets related to SBOM compliance workflows
  4. Increased adoption of GitLab's SBOM features for compliance use cases

Acceptance Criteria:

  • GraphQL API returns clear direct/transitive indicators for dependencies
  • SBOM export files include dependency type information in a standards-compliant way
  • API documentation clearly explains how to filter by dependency type
  • Works consistently across all supported package managers
  • Handles edge cases (dependencies that are both direct and transitive)

Links / references

Edited by 🤖 GitLab Bot 🤖