Vulnerability Scanning
Relevant source files
The following files were used as context for generating this wiki page:
Vulnerability scanning in Harbor Next provides a robust framework for detecting security risks within container images and other artifacts. It supports multi-scanner integration through a pluggable adapter architecture, allowing users to choose their preferred security scanners (such as Trivy) to analyze image layers for known Common Vulnerabilities and Exposures (CVEs).
The system encompasses the entire lifecycle of security analysis, from triggering manual or automated scans upon image push to generating detailed reports and enforcing deployment security policies. By leveraging a centralized Security Hub, administrators can gain system-wide visibility into the security posture of all projects.
Core Scanning Architecture
The scanning logic is centralized in the basicController, which coordinates interactions between artifacts, scanner registrations, and the job service.
Scanning Workflow
When a scan is triggered, the controller performs the following steps:
- Scanner Selection: Identifies the scanner registered for the project or the system default.
- Artifact Collection: Resolves the target artifact. If it is an image index, it recursively collects child artifacts supported by the scanner.
- Job Launching: Creates a manual or automated execution, generates robot accounts with necessary permissions, and enqueues tasks in the Job Service.
Sources: src/controller/scan/base_controller.go:193-240, src/controller/scan/base_controller.go:537-560
The diagram shows the high-level flow from triggering a scan to the creation of asynchronous tasks.
Sources: src/controller/scan/base_controller.go:193-300
Scannable Artifact Resolution
The system determines scannability by walking the artifact tree. An artifact is scannable if:
- The scanner has direct capability for the artifact's MIME type.
- The artifact is an image index containing referenced artifacts supported by the scanner.
Sources: src/controller/scan/base_controller.go:154-184
Data Transformation and Storage
Harbor Next uses a relational schema to store vulnerability records, which improves query performance and enables the Security Hub features.
Report Conversion
Raw JSON reports received from scanner adapters (V1 schema) are post-processed into a normalized relational schema (V2). The nativeToRelationalSchemaConverter parses raw data and populates the vulnerability_record and report_vulnerability_record tables.
Sources: src/pkg/scan/postprocessors/report_converters.go:44-67, make/migrations/postgresql/0050_2.2.0_schema.up.sql:533-560
Database Schema Summary
| Table | Description | Key Fields |
|---|---|---|
vulnerability_record | Stores unique vulnerability details per scanner. | cve_id, package, severity, cvss_score_v3 |
report_vulnerability_record | Maps scan reports to vulnerability records. | report_uuid, vuln_record_id |
scan_report | Stores metadata about the scan execution. | uuid, digest, registration_uuid, mime_type |
Sources: make/migrations/postgresql/0050_2.2.0_schema.up.sql:533-560, src/pkg/scan/postprocessors/report_converters.go:183-214
Deployment Security Enforcement
The system includes middleware to prevent the distribution of vulnerable images based on project-level security policies.
Vulnerability Prevention Logic
When an artifact is pulled via GET /v2/<name>/manifests/<reference>, the vulnerable middleware intercepts the request. It checks:
- Project Policy: Is "Prevent vulnerable images from running" enabled?
- Severity Threshold: Does the image contain vulnerabilities equal to or higher than the configured threshold (e.g., Medium, High, Critical)?
- CVE Allowlist: Are the detected vulnerabilities exempted by the project or system allowlist?
Sources: src/server/middleware/vulnerable/vulnerable.go:42-100
This sequence illustrates how the middleware enforces deployment security during image pull operations.
Sources: src/server/middleware/vulnerable/vulnerable.go:42-136
Security Hub and Reporting
The Security Hub provides a unified view of the security state across the entire Harbor instance.
Security Summary Data
The system aggregates vulnerability data into summaries containing:
- Total/Scanned Artifacts: Coverage metrics for the entire registry.
- Vulnerability Distribution: Counts of Critical, High, Medium, Low, and None severity issues.
- Dangerous Artifacts: The top 5 artifacts with the most critical vulnerabilities.
- Dangerous CVEs: The top 5 most impactful CVEs based on CVSS scores.
Sources: src/server/v2.0/handler/security.go:47-64, api/v2.0/swagger.yaml:1894-1940
API Endpoints for Security Hub
| Endpoint | Method | Description |
|---|---|---|
/security/summary | GET | Returns the system-wide vulnerability summary. |
/security/vul | GET | Lists vulnerabilities with filtering by project, repository, or CVE ID. |
/projects/{project_name}/artifacts/{reference}/scan | POST | Triggers a scan for a specific artifact. |
/scans/all/metrics | GET | Returns metrics for the "Scan All" background job. |
Sources: api/v2.0/swagger.yaml:1260-1288, api/v2.0/swagger.yaml:1535-1560, src/server/v2.0/handler/security.go:35-45
Conclusion
Vulnerability scanning in Harbor Next is a comprehensive system that bridges the gap between passive storage and active security enforcement. By automating the scanning process and providing tools like the Vulnerability Prevention middleware and Security Hub, Harbor ensures that only artifacts meeting defined security standards are deployed into production environments. The transition to a relational storage model for vulnerabilities further empowers administrators with performant, system-wide security analytics.