Configuring Harbor’s Built‑In Vulnerability Scanner for Push‑Triggered Scans

Problem

When you push a container image to a private registry, you want immediate feedback on known vulnerabilities without setting up an external scanner or managing separate cron jobs. Harbor includes a vulnerability‑scanning service that can be turned on and configured to run automatically on each push, but the exact steps to enable it and tune its performance are not always obvious.

Solution Overview

Harbor’s scanner runs as a side‑car service that pulls vulnerability feeds (from Trivy or Clair), inspects image layers, and stores results per‑artifact. By enabling the scanner in harbor.yml and adjusting a few parameters, you get:

• Automatic scans on image push (or on a schedule)
• Severity‑rated findings with CVE links visible in the UI and API
• Control over scan depth via concurrency and feed‑update frequency

Enabling the Scanner

1. Edit Harbor configuration – on the host where Harbor is installed, open harbor.yml (usually /etc/harbor/harbor.yml). You need root or sudo privileges to modify this file.
2. Activate the scanner service – set the scanner block to true and choose either Trivy or Clair. Example for Trivy:

scanner:
  # Set to true to enable the built‑in vulnerability scanner
  enabled: true
  # Choose the scanner backend: trivy or clair
  # Trivy is the default in Harbor 2.8+
  # If you prefer Clair, set scanner: clair and configure its endpoint
  # Trivy specific settings
  trivy:
    # Interval (in hours) at which Trivy updates its vulnerability DB
    # Lower values give fresher data but increase CPU/I/O load
    update_interval: 12
    # Number of concurrent scan jobs; adjust based on available cores
    # A safe starting point is the number of CPU cores divided by 2
    concurrent: 2
    # Optional: skip scanning of certain namespaces or tags
    # ignore:
    #   - "*/dev/*"
    #   - "*latest"

1. Apply the changes – run the Harbor installer script to regenerate docker-compose.yml and restart the services:

# Run from the Harbor installation directory (requires sudo)
sudo ./prepare
sudo docker-compose down
sudo docker-compose up -d

Example: Scanning an Image on Push
Assume you have a test image myrepo/test-app:1.0 that contains an old version of curl with a known CVE (e.g., CVE‑2021‑22883).

  
Push the image to your Harbor project (you need push permission on the target project):

docker login harbor.example.com
# Tag the image for your Harbor project
 docker tag myrepo/test-app:1.0 harbor.example.com/library/test-app:1.0
# Push
 docker push harbor.example.com/library/test-app:1.0


  
Wait for the scan to finish – Harbor automatically triggers a scan after the push completes. In the UI, navigate to the repository → test-app → tag 1.0 and open the Vulnerabilities tab. You should see a list of findings, including the CVE for curl.
  
Check via API (optional) – with a token that has read scope on the repository:

# Get the artifact digest (example)
 curl -k -u "username:token" \
   "https://harbor.example.com/api/v2.0/projects/library/repositories/test-app/artifacts?reference=1.0" | jq '.[0].digest'
# Suppose the digest is sha256:abc123...
 curl -k -u "username:token" \
   "https://harbor.example.com/api/v2.0/scanner/reports/sha256:abc123..." | jq .

The JSON report includes fields such as severity, description, and links to the CVE database.
Trade‑offs and Tuning

  
Scan depth vs. performance – Enabling language‑specific scanners (e.g., for npm, pip) increases CPU and memory usage because the scanner must unpack additional layers and parse package manifests. If you notice increased push latency, reduce concurrent or increase update_interval.
  
Feed latency – Vulnerability feeds are updated on the interval you set (update_interval). In high‑security environments you may want a shorter interval (e.g., 4 hours) but monitor the host’s I/O; otherwise rely on the default 12 hours.
  
Namespace/tag exclusions – To avoid scanning noisy development images, add patterns under ignore in the Trivy section. This saves cycles without affecting production images.

Verifying the Setup

  
Push a known‑vulnerable image (as shown above).
  
Confirm the UI or API report lists the expected CVE IDs and severity levels.
  
Disable the scanner temporarily (enabled: false in harbor.yml) and repeat the push; the vulnerability tab should be empty, proving the scanner is the source of the findings.
  
Adjust concurrent or update_interval and observe changes in scan duration (measure with time around the push) and feed freshness.

These steps give you confidence that the scanner is active, correctly configured, and tunable to your workload.
Actionable Closing
With Harbor’s built‑in vulnerability scanner you can shift security left: every push yields immediate, actionable insights without external tooling. Start by enabling the scanner in harbor.yml, choose a sensible concurrency level, and set an update interval that balances freshness with resource use. Verify with a test image containing a known CVE, then tune based on observed scan times and your registry’s traffic. This approach keeps your pipeline secure while keeping operational overhead low.