Harbor Scanner Cache Refresh on Updated Vulnerability Database

To ensure Harbor reflects the latest vulnerability data after the underlying scanner (like Trivy) updates its database, you must explicitly trigger a re-scan. Harbor caches scan results in PostgreSQL linked to the image digest; it does not automatically invalidate these results when the scanner's local database changes.

Recommended API Sequence for Fresh Scans

To force a scan without disrupting audit trails or deleting history, use the Harbor API to initiate a new scan task. This creates a new entry in the scan history rather than deleting previous records.

1. Initiate Scan: Send a `POST` request to `/api/projects/{project_name}/artifacts/{artifact_name}/scan?force=true`. The force=true query parameter (available in Harbor 2.2+) ensures the scanner bypasses the local-cache check.
2. Monitor Status: Use the task ID returned in the response to poll `/api/tasks/{task_id}` until the status is `succeeded`.
3. Retrieve Results: Once complete, fetch the updated vulnerabilities via `/api/projects/{project_name}/artifacts/{artifact_name}/vulnerabilities`.

Interaction: scan_overwrite vs force=true

These flags operate at different stages of the scan lifecycle:

• scan_overwrite=true: This is a global or project-level configuration. When enabled, Harbor replaces the existing vulnerability report in the database with new data whenever a scan is triggered. It manages the state of the result.
• force=true: This is a request-level override. It tells the scanner to perform the work immediately regardless of whether Harbor thinks the scan is already current.

If both are enabled, force=true ensures the scan happens now, and scan_overwrite ensures the results replace the old data in the UI once the scan finishes.

Best Practices for Compliance-Heavy Environments

In environments where audit integrity is critical, follow these strategies:

• Avoid API Deletion: Avoid using DELETE methods on scan results, as this erases the audit trail of what was discovered when.
• Use Versioned Results: Instead of overwriting, rely on Harbor's ability to maintain scan history. This allows auditors to see that an image was "clean" at deployment time but flagged two weeks later.
• Webhook Logging: Configure Harbor webhooks to stream scan results to an external SIEM or logging solution. This ensures an immutable record of vulnerabilities exists outside of the Harbor database state.

Note: This analysis assumes Harbor 2.2 or later using the Trivy scanner adapter. If you are using older versions, the force=true parameter may be unavailable.