SBOM Generation & Management
Relevant source files
The following files were used as context for generating this wiki page:
The SBOM (Software Bill of Materials) Generation & Management system in Harbor provides the capability to scan container images and OCI artifacts to identify their software components and licenses. It produces structured data (typically in SPDX format) that documents the software supply chain for a given artifact.
This system integrates with Harbor's scanning framework, utilizing a dedicated scan handler to coordinate with external scanners (like Trivy) and managing the resulting SBOM reports as artifact accessories. Users can trigger SBOM generation manually via the UI or API, or configure automatic generation upon artifact push at the project level.
Sources: src/pkg/scan/sbom/sbom.go:48-60, api/v2.0/swagger.yaml:1208-1215
Architecture & Components
The SBOM system is built upon a modular architecture involving a backend manager, a scan handler, and a frontend presentation layer.
SBOM Manager
The Manager interface defines the core operations for persisting and retrieving SBOM report metadata. It handles the lifecycle of report records in the database, including creation, updates, and deletion based on artifact IDs or extra attributes like digests.
Sources: src/pkg/scan/sbom/manager.go:28-66
Scan Handler
The scanHandler is the primary orchestrator for the SBOM generation process. It implements Harbor's scan framework interfaces to:
- Define required parameters (e.g., supported media types like
application/spdx+json). - Manage report placeholders during the initiation phase.
- Perform post-scan logic, which includes retrieving the raw scanner output and generating an accessory artifact within the registry to store the actual SBOM content.
Sources: src/pkg/scan/sbom/sbom.go:63-125
Data Flow for SBOM Generation
The following diagram illustrates the flow from a generation request to the creation of an SBOM accessory.
The flow ensures that the heavy SBOM data is stored as a standard OCI artifact (accessory), while the database tracks the metadata and status.
Sources: src/pkg/scan/sbom/sbom.go:88-110, src/pkg/scan/sbom/manager.go:94-118
SBOM Artifact Accessories
Unlike standard vulnerability reports which are purely database-driven, Harbor manages the generated SBOM as an "Accessory".
- Accessory Type:
sbom.harbor - MIME Type:
application/vnd.goharbor.harbor.sbom.v1 - Relationship: The SBOM artifact is linked to its subject artifact via the subject's digest.
When an SBOM is successfully generated, the scan handler creates an accessory artifact. This allows the SBOM to be managed with standard registry features like replication and tag retention.
Sources: src/pkg/scan/sbom/sbom.go:50-51, src/portal/src/app/base/project/repository/artifact/artifact.ts:108
API Endpoints
The system is exposed via Harbor's V2.0 API. Key operations include triggering scans and retrieving report logs.
| Method | Path | Description |
|---|---|---|
POST | /projects/{project_name}/repositories/{repository_name}/artifacts/{reference}/scan | Triggers a scan. Requires scan_type set to sbom. |
POST | /projects/{project_name}/repositories/{repository_name}/artifacts/{reference}/scan/stop | Cancels a running SBOM generation job. |
GET | /projects/{project_name}/repositories/{repository_name}/artifacts/{reference}/scan/{report_id}/log | Retrieves the log for a specific SBOM generation task. |
GET | /projects/{project_name}/repositories/{repository_name}/artifacts/{reference}/additions/sbom | Retrieves the SBOM addition link for an artifact. |
Sources: api/v2.0/swagger.yaml:1208-1285, api/v2.0/swagger.yaml:1385-1395
Reporting and Status
The system tracks the progress of generation through several states.
Scan Statuses
- Pending/Queued: The task is waiting for a worker.
- Running/Generating: The scanner is currently processing the artifact.
- Success/Completed: The SBOM is generated and the accessory is pushed.
- Error: The generation failed (logs are available for debugging).
- Stopped: The task was manually cancelled.
Sources: src/portal/src/app/base/project/repository/artifact/sbom-scanning/sbom-scan.component.ts:125-155
Report Summary Schema
The database stores a summary of the SBOM generation which includes metadata about the process:
type Summary map[string]any
const (
SBOMRepository = "sbom_repository"
SBOMDigest = "sbom_digest"
StartTime = "start_time"
EndTime = "end_time"
Duration = "duration"
ScanStatus = "scan_status"
Scanner = "scanner"
)
Sources: src/pkg/scan/sbom/model/summary.go:21-39
Implementation Details
Scan Handler Logic
The logic for creating placeholders and managing the relationship between the report and the artifact is handled in MakePlaceHolder.
func (h *scanHandler) MakePlaceHolder(ctx context.Context, art *artifact.Artifact, r *scanner.Registration) (rps []*scanModel.Report, err error) {
mgr := h.SBOMMgrFunc()
mimeTypes := r.GetProducesMimeTypes(art.ManifestMediaType, v1.ScanTypeSbom)
// ... logic to delete old reports and create new UUIDs ...
for _, mt := range mimeTypes {
report := &sbom.Report{
ArtifactID: art.ID,
RegistrationUUID: r.UUID,
MimeType: mt,
MediaType: sbomMediaTypeSpdx,
}
// ... persist to DB via manager ...
}
return reports, nil
}
Sources: src/pkg/scan/sbom/sbom.go:193-228
Client Interaction
The UI manages the generation process by polling the artifact status and checking for the presence of the sbom_overview field in the artifact response. It uses an EventService to coordinate between components when a scan starts or stops.
Sources: src/portal/src/app/base/project/repository/artifact/sbom-scanning/sbom-scan.component.ts:178-215
Conclusion
The SBOM Generation & Management module provides a robust framework for identifying artifact components. By leveraging the OCI accessory model, it ensures that transparency data is stored as securely and reliably as the artifacts themselves, while the integrated scan handler manages the lifecycle from request to SPDX report generation.