Harbor

Harbor is a self-hosted CNCF registry whose security model is built around projects: every image lives under harbor.example.com/<project>/<image>, and access controls are scoped per project. Robot accounts are the right primitive for HarborGuard — they are revocable, do not occupy a user seat, and can be scoped narrowly.

Auth options

Add the registry

1. Registries → Connect Registry.
2. Registry URL — the Harbor portal URL minus the path, for example harbor.example.com. Don't include /harbor/projects etc.
3. Harbor isn't auto-detected from the URL; pick Harbor in the provider field if the wizard falls back to Custom.
4. Cloud mode: enter the robot name + secret.
5. If your Harbor uses HTTP (very common for internal staging), enable Allow HTTP / insecure.
6. Save.

Harbor uses real /v2/_catalog so HarborGuard's catalog enumeration works end-to-end.

Robot account scopes

When creating the robot, grant at minimum:

• repository: pull, list
• artifact: read
• tag: list

Avoid push, delete, and helm-chart-write — HarborGuard only reads.

For a system-wide robot (Harbor 2.2+), add repository(*): pull, list plus artifact(*): read. The * is required; granting repository: pull without a project selector silently scopes to nothing.

Push-event sync

Harbor projects can fire webhooks on push.

1. Project → Webhooks → New Webhook.
2. Notify type: http.
3. Endpoint: https://<your-harborguard-host>/api/webhooks/harbor.
4. Event types: Artifact pushed.
5. Set the registry's schedule to on_push.

For multi-project Harbor instances, configure one webhook per project.

Common pitfalls

• Robot prefix. Harbor prepends robot$ (project robot: robot$<project>+name; system robot: robot$name). The wizard's username field must contain the full prefixed name, exactly as Harbor's UI shows it. Stripping the prefix is the single most common 401 cause.
• Cross-project robots don't exist (pre-2.2). A project-scoped robot cannot list any other project. Either use a system robot or add multiple HarborGuard registry connections, one per project.
• Self-signed CAs. Harbor is often deployed with a private CA. Cloud-mode connections will fail TLS — deploy a sensor inside the network.
• Replication-only artifacts. If a project is the destination of a Harbor replication and the source has been deleted, manifests may become "unknown" — HarborGuard reports the manifest, scan fails on pull. This is a Harbor-side cleanup issue.
• Vulnerability scanning collision. Harbor has its own scanner integration. Disable Harbor's own scan-on-push if you want HarborGuard to be the system of record — both running together is supported but doubles network egress.

Troubleshooting