Docker Hub

Docker Hub is the default for the public Docker ecosystem and the easiest registry to connect — but it's also the registry where rate limits and silent throttling cause the most operational pain. The single most important thing you can do is authenticate, even for public images.

Auth options

PATs are created at hub.docker.com → Account Settings → Security → New Access Token. Grant the Public Repo Read-only scope for public-only catalogs, or Read & Write if you also use the same token for pushes elsewhere. HarborGuard never writes.

Add the registry

1. Open Registries → Connect Registry.
2. Registry URL — docker.io (or the full registry-1.docker.io; both resolve).
3. The wizard tags the connection as Docker Hub Detected.
4. Pick Cloud scan method.
5. Username — your Docker Hub account name. Password / Token — the PAT.
6. Save. The first catalog sync runs immediately; tag-filter defaults to *.

For sensor mode, skip the credential step and pass the same PAT to the sensor at deploy time.

Required permissions

A read-only PAT is sufficient. HarborGuard calls:

• GET /v2/ (auth probe)
• GET /v2/<namespace>/<image>/tags/list
• GET /v2/<namespace>/<image>/manifests/<tag>
• GET /v2/<namespace>/<image>/blobs/<digest> (during scan only)

Docker Hub does not implement /v2/_catalog. HarborGuard discovers your repositories through the Hub REST API (hub.docker.com/v2/repositories/<namespace>) using the namespaces tied to the authenticated user.

Push-event sync

Hub webhooks fire on push events for automated builds and Pro/Team/Business plans only — they are not available on the free tier. If your account qualifies, point the webhook at:

https://<your-harborguard-host>/api/webhooks/dockerhub

Then set the registry's schedule to on_push in the registry detail view. On free accounts, fall back to daily.

Common pitfalls

• Rate limits. Anonymous pulls are capped at 100 / 6 hours per source IP; authenticated free accounts at 200 / 6 hours; paid accounts get higher limits. A large catalog with many tags can burn through this in a single sync. Always authenticate, and use tag filtering to skip release candidates and -debug variants.
• Library namespace. Official images live under library/, but pulls work without the prefix (nginx is library/nginx). HarborGuard normalizes both forms.
• Two-factor accounts must use a PAT. Username + account password fails the /v2/ token exchange when 2FA is enabled — the error reads "authentication failed", not "2FA required". Switch to a PAT.
• Org vs personal namespaces. A PAT only sees repos the issuing user can read. To scan an org's private images, the user must be a member of the org with read access.

Troubleshooting