Harbor

Connect Harbor to Safeguard. The robot account permissions Safeguard needs, which credentials work, and step-by-step setup.

Availability

This integration is switched on per workspace. If you do not see the card under Integrations, ask your Safeguard contact.

What it does

The Harbor card connects Safeguard to the projects in a Harbor registry (Harbor 2.0 or later). Safeguard lists your projects, every repository in them and every tag, and each image you select becomes a project that Safeguard scans for an SBOM and vulnerability findings. Each scan is pinned to the digest the tag points at when the scan starts, and pulls the image with the credential you connect. Beside each tag Safeguard shows Harbor's own scan summary and whether the image is signed, labelled as Harbor's; Safeguard's findings come from its own scan. Find the card under Integrations on the Project/Product tab.

Public vs private

	Public	Private
What you enter	The Harbor URL	The Harbor URL and a robot account or user
Credential needed	None. Only projects marked Public in Harbor are read	A robot account and its secret, or a user and its password or CLI secret
What you can scan	Public projects	Every project the credential can see, or the projects you name

Supported auth methods

Method (dialog label)	Use it when	Notes
Robot account	Recommended	A project robot (`robot$<project>+<name>`) for one project, or a system robot (`robot$<name>`) for several
Password	No robot account is allowed	A Harbor user with its password, or its CLI secret when Harbor signs users in with OIDC

Permissions required

Safeguard only reads. It never pushes, deletes or retags images, and never changes project settings, except the webhook you add yourself (below).

Robot account

Permission	Required?	What Safeguard uses it for
Repository: List	Required	Listing repositories (`/api/v2.0/projects/{project}/repositories`)
Repository: Pull	Required	Reading manifests for digests and pulling images for scans
Artifact: List and Read	Required	Listing artifacts with their tags, digests, Harbor scan summary and signatures
Project: Read (system robot)	Required for a system robot	Listing the projects it covers
Repository: Push, Delete; Artifact: Delete; any other permission	Not used	Safeguard never writes

Least privilege: a project robot on each project to scan with only Repository List and Pull and Artifact List and Read, and an expiry.

Password

Role	Required?	What Safeguard uses it for
Limited Guest (or Guest) on each project	Required	The same reads as above

Token types

Credential type	Works?	Notes
Project robot account	Yes (recommended)	Scoped to one project
System robot account	Yes	Covers several projects; give it only the read permissions above
User and CLI secret (OIDC)	Yes	The CLI secret is under User Profile > CLI secret
User and password (database or LDAP auth)	Yes	Use a dedicated read-only user
Admin user	Works, not recommended	Far more than Safeguard needs

Expiry: set robot accounts to expire in 90 days or less, and refresh the secret before then. An expired robot fails with the "rejected the credential" message below.

What we never need: Push, Delete, Project admin or Maintainer roles, system administrator rights, or any configuration permission.

Step-by-step setup

Create the credential in Harbor

Open the project, then Robot Accounts > + New Robot Account.
Give it a name and an expiry, and tick only Repository: List, Pull and Artifact: List, Read.
Click Add. Copy the robot's name (robot$<project>+<name>) and secret; Harbor shows the secret once.

Or with the Harbor API

curl -u admin -X POST -H "Content-Type: application/json" https://harbor.example.com/api/v2.0/robots -d '{
  "name": "safeguard", "level": "project", "duration": 90,
  "permissions": [{"kind": "project", "namespace": "<project>", "access": [
    {"resource": "repository", "action": "list"}, {"resource": "repository", "action": "pull"},
    {"resource": "artifact", "action": "list"}, {"resource": "artifact", "action": "read"}]}]}'

Connect it in Safeguard

Open Integrations and choose the Project/Product tab.
Click Connect on the Harbor card.
Choose Private (or Public), enter a Name and the Harbor URL, for example https://harbor.example.com.
Private: pick Robot account and enter the Robot account name and the secret (or Password with a username).
Projects (optional): limit listing to some projects.
Click Verify Credentials (or Check anonymous access). "Connected. N Docker repositories are readable." means Harbor accepted the credential.
Click Next, select repositories and tags, and choose a connect option (fast, progressive or deep scan).

Webhooks and triggers

Scan on push is optional. Open the connection's edit dialog and expand Scan on push (optional) for the Webhook URL (https://api.safeguard.sh/scm/api/v1/registry-webhooks/harbor/<connection id>) and the Secret. In Harbor, open the project, then Webhooks > + New Webhook: Notify Type http, Event Type Artifact pushed, Endpoint URL the URL above, Auth Header the secret, and keep certificate verification on. Payload format Default or CloudEvents both work. Add one webhook per project.

Harbor sends the Auth Header in Authorization; Safeguard refuses deliveries without the matching secret. A pushed tag is scanned as the version <tag>-<first 12 characters of the digest>. Without a webhook, rescan on a schedule under Integrations > Scheduled.

What we read and store

Read: project names, repository names, artifacts with their tags, digests and push times, Harbor's scan summary and signature accessories, and the images you select for scanning.
Stored: the connection's settings, the SBOM and findings of each scanned image with its digest, and the credential, which is encrypted at rest and never shown again after you save it.
Not stored: image layers. The image is read for the scan and not kept. Harbor's own vulnerability reports are not imported as Safeguard findings.
No customer data from this integration is sent to third-party LLMs.

Troubleshooting

Message you see	Cause	Fix
`Harbor rejected the credential. A robot account's username is robot$<name> (system robot) or robot$<project>+<name> (project robot), with its secret ...`	Wrong robot name or secret, a disabled or expired robot, or a user without its CLI secret	Copy the full robot name, including `robot$`, and refresh its secret
`The account <user> signed in but can see no projects. ...`	The robot covers no project	Add the projects to the robot's permissions
`The Harbor account cannot read <path> ... A project robot needs Repository: List and Pull and Artifact: Read and List on that project ...`	A permission is missing	Edit the robot and tick the missing permissions
`Harbor at <host> has no public projects. ...`	Public tab with no public project	Mark a project Public, or use the Private tab
`No Harbor v2 API at <url>. Check the URL (Harbor 2.0 or later).`	Wrong URL, or Harbor 1.x	Use the address you sign in with; upgrade Harbor 1.x
`The TLS certificate of <host> is not trusted ...`	A self-signed or private certificate	Serve Harbor with a certificate from a public certificate authority

Rotation and disconnect

Rotate: refresh the robot's secret (Robot Accounts > the robot > Refresh Secret), find the connection under Project Configurations on the Project/Product tab, choose Update, enter the new secret, verify and save.
Disconnect: choose Delete from the connection's menu under Project Configurations and confirm. Then delete the robot account and the project webhooks that point at Safeguard.

Vendor references

Harbor API v2.0 (swagger), checked 2026-10-16.
Configure webhooks, checked 2026-10-16.
Create robot accounts, checked 2026-10-16.

Harbor

On this page