Enabling Harbor’s Built‑in Trivy Scanner: Decision, Trade‑offs, and Step‑by‑Step Setup

Decision: Turn on Harbor’s Trivy Scanner

When a registry needs automated, on‑push vulnerability assessment, Harbor’s built‑in Trivy scanner (available from Harbor 2.7 onward) is a lightweight, fast option that requires no external services. The key decision is whether the speed and simplicity of Trivy outweigh the deeper analysis offered by alternatives like Clair or Anchore.

Constraints to Consider

• Harbor UI or API access with admin privileges.
• Trivy binary installed on the machine that runs Harbor’s scanner service.
• Network connectivity from the scanner host to Trivy’s vulnerability database (https://github.com/aquasecurity/trivy-db).
• Adequate CPU and memory: a single scan can use 1–2 GB RAM and 0.5–1 CPU core, depending on image size.
• Asynchronous scan lifecycle: a pushed image may take several minutes to finish.

Supported Alternatives

Harbor can also integrate with third‑party scanners. The most common ones are Clair and Anchore. Below is a compact comparison of the three options.

Feature	Trivy	Clair	Anchore
Installation effort	Single binary, make install	Docker Compose + database	Docker + policy engine
Scan speed	Fast – lightweight OS+app CVE checks	Moderate – deeper layer analysis	Slow – policy evaluation adds overhead
Resource usage	Low – <2 GB RAM	High – requires DB, can use >4 GB RAM	High – policy engine + DB
Comprehensiveness	Broad OS+app CVEs, may miss some deep OS‑only CVEs	Deep OS layer analysis, more CVEs detected	Policy‑based, can enforce custom rules
Community support	Active, frequent updates	Mature, long‑standing	Enterprise‑grade, commercial support available
Maintenance	Update binary, DB sync	DB migrations, service restarts	Policy updates, DB scaling

Trade‑offs

• Speed vs Depth: Trivy is ideal for rapid feedback in CI pipelines, but Clair may surface CVEs that Trivy’s lightweight engine misses.
• Resource vs Complexity: Trivy keeps Harbor simple; Clair and Anchore add database services and policy layers that increase operational overhead.
• Compliance vs Flexibility: Anchore’s policy engine is great for strict compliance, but if you only need CVE visibility, Trivy suffices.
• All scanners rely on up‑to‑date vulnerability databases; neglecting updates can leave recent CVEs undetected.

Concrete Implementation Workflow

1. Install Trivy on the scanner host

   # On the host that runs Harbor's scanner service
   # Replace <version> with the desired release, e.g., 0.54.0
   curl -L https://github.com/aquasecurity/trivy/releases/download/v<version>/trivy_${lt;version>}_Linux-64bit.tar.gz | tar -xz -C /usr/local/bin
   

   Verify installation: trivy --version should return the version string.

2. Configure Harbor to use Trivy

   # In Harbor UI:
   # 1. Go to Settings → Security → Scanner
   # 2. Enable “Trivy” and click Save
   # 3. Optionally, set “Scan on push” to true for automatic scanning
   

   Alternatively, via API (admin token required):

   curl -X POST https://<harbor-host>/api/v2.0/settings/scanner -H "Content-Type: application/json" -H "Authorization: Bearer <admin_token>" -d '{"name":"trivy","enabled":true,"scanOnPush":true}'
   

3. Push a test image

   # Build or pull a simple image
   docker pull alpine:latest
   # Tag and push to Harbor
   docker tag alpine:latest <harbor-host>/<project>/alpine:latest
   docker push <harbor-host>/<project>/alpine:latest
   

   After the push completes, Harbor will enqueue a scan job.

4. Validate the scan

   # Wait a few minutes, then query the scan status via API
   curl -X GET https://<harbor-host>/api/v2.0/projects/<project>/repositories/alpine/artifacts/<digest>/scan -H "Authorization: Bearer <admin_token>"
   

   The JSON response will contain a scanResult array with CVE details. In the UI, navigate to the image’s “Vulnerabilities” tab to see the same data.

5. Check Harbor logs

   # On the Harbor host
   grep -i trivy /var/log/harbor/harbor.log
   

   Look for entries like “Trivy scan started” or “Trivy scan finished” to confirm execution and spot any errors.

Practical Verification Checklist

• Scanner status in UI shows Trivy enabled.
• API call returns a non‑empty scanResult array.
• Log entries contain Trivy keywords with no error messages.
• Resource usage during scan stays within allocated limits (monitor via top or Harbor’s metrics).

Limitations & Mitigations

• Asynchronous scans: Expect a delay between push and report availability. Use the API to poll status if automated.
• CPU spikes: Heavy scans can temporarily impact Harbor’s API responsiveness. Schedule scans during low‑traffic windows or increase host resources.
• DB lag: Trivy’s vulnerability database updates weekly. Run trivy image --download-db-only regularly to keep the DB fresh.
• Missing CVEs: If compliance requires exhaustive coverage, consider running Clair in parallel or integrating Anchore for policy enforcement.

By following this guide, you can quickly enable Harbor’s Trivy scanner, understand its trade‑offs compared to other scanners, and verify that scans run successfully and reliably in your environment.