OCI Registry Integration

Overview

The OCI Registry integration — the Container Registry card in Admin > Integrations — lets you connect any OCI-compliant container registry to Fencer so you can scan container images for vulnerabilities. Fencer discovers repositories and tags from your registry, then runs security scans against those images. The setup guide covers Docker Hub, GitHub Container Registry (GHCR), Azure Container Registry (ACR), Quay.io, and any self-hosted registry that implements the OCI Distribution Specification (such as Harbor, Nexus, or GitLab Registry).

Prerequisites

The Administrator role in your Fencer organization
A valid subscription
Your registry URL
Credentials are optional for public registries that allow anonymous access (for example public Docker Hub). Username and password or an access token are required only for private registries.

How it works

When you connect a registry, Fencer validates access by testing the connection against the registry’s /v2/ API endpoint. Public registries can be connected with empty credentials when that endpoint allows anonymous access. Private registries still require a username and password (or token). Once connected, Fencer creates a registry asset in your organization that tracks your container images.

Public (credential-less) connections do not scan the registry catalog. You list the specific images to scan instead, up to 20 references. A tagged reference (for example nginx:1.27) is scanned as that tag; a reference without a tag is scanned as latest when that tag exists.

With Scan registry images turned on, Fencer scans the images you listed, or — when the connection uses a password — discovers repositories and tags from the registry catalog. It starts this discovery and scan as soon as you connect, then repeats it on your scan schedule: every day on plans with daily scans, otherwise every Monday. Fencer also uses each connection’s credentials whenever it needs to pull an image from that registry for another scan, for example an image your cloud integrations find running in a container.

Usage / Configuration

Connecting a registry

Go to Admin > Integrations.
Click the Container Registry card under Available Integrations, then click Continue.
In the setup guide beside the form, select your registry provider (Docker Hub, GitHub (GHCR), Azure (ACR), Quay.io or Self-Hosted) to see provider-specific credential instructions.
Fill in the connection form:
- Name (optional): A friendly name for this connection. Defaults to the URL if left blank.
- URL: Your registry URL (e.g., ghcr.io/myorg, myregistry.azurecr.io, registry.example.com). For Docker Hub, use your username or registry.hub.docker.com.
- Username: Your registry username or service account. Leave blank for public registries.
- Password: Your registry password, personal access token, or robot account token. Leave blank for public registries.
- Images: Required for public registries. One image per line, up to 20 (for example nginx or nginx:1.27). For registries other than Docker Hub, include the host (ghcr.io/org/image:tag).
- Scan registry images (on by default): Scan the listed images, or the registry catalog when using credentials.
Click Connect. Fencer validates access before saving. Anonymous connections are rejected if the registry requires authentication.

Provider-specific credentials

Docker Hub: Create a personal access token with Read-only permissions at Docker Hub > Account settings > Personal access tokens. Use your Docker Hub username and the token as the password.

GitHub Container Registry (GHCR): Create a personal access token (classic) at GitHub > Settings > Developer settings > Personal access tokens > Tokens (classic). Select the read:packages scope. Use your GitHub username and the token as the password.

Azure Container Registry (ACR): Create a service principal with the AcrPull role on your registry. Use the service principal’s application ID as the username and its password as the password.

Quay.io: Create a robot account in your organization with read permissions. Use the robot account name (e.g., organization+robot_name) as the username and the robot token as the password.

Self-hosted registries: Contact your registry administrator for credentials with read access. Your registry must support the OCI Distribution Specification.

Editing a connection

Go to Admin > Integrations and find your Container Registry connection.
Click Edit (the pencil icon) to update the name, URL, username, password, images, or Scan registry images.
Leave the password field blank to keep the existing password, then click Save changes.

Disconnecting a registry

On the connection’s card in Admin > Integrations, click Remove (the trash icon), then confirm with Remove. This soft-deletes the registry asset and clears stored credentials.

Examples

Connecting public Docker Hub images without credentials:

Go to Admin > Integrations and click the Container Registry card, then Continue.
Select Docker Hub in the setup guide.
Enter docker.io in the URL field.
Leave Username and Password blank.
In Images, list the public images to scan (for example nginx or nginx:1.27), one per line, up to 20.
Leave Scan registry images on.
Click Connect.

Fencer confirms the registry allows anonymous /v2/ access, checks that each listed image can be read, and records those artifacts as public-registry images. It does not catalog-scan the rest of the registry.

Connecting Docker Hub to scan private images:

Go to Admin > Integrations and click the Container Registry card, then Continue.
Select Docker Hub in the setup guide.
Enter your Docker Hub username in the URL field (e.g., mycompany).
Enter your Docker Hub username and personal access token.
Leave Scan registry images on to discover and scan all images in your account.
Click Connect.

Fencer discovers all repositories under your account, enumerates their tags, and triggers vulnerability scans on the discovered images.

Troubleshooting

“This registry requires authentication”: The registry does not allow anonymous access. Enter a username and password, or connect a public registry. Open Source plans cannot use authenticated registries.
“Unable to connect to container registry with the provided credentials”: Verify that your username and password/token are correct and that the token has read access. For Docker Hub, ensure you are using a personal access token, not your account password.
“This registry URL returns too many repositories to scan”: The catalog lists more than 100 repositories. Use a more specific URL that includes a namespace or organization (for example ghcr.io/myorg).
Public registries require specific images to scan: Add at least one image reference. Public connections do not scan the full registry catalog.
You can specify at most 20 images: Remove extra image references. Credentialed connections can omit the list to scan the registry catalog instead.
Each image must belong to the connected registry: Include the registry host for non-Docker Hub images (for example ghcr.io/org/image:tag).
“Could not access one or more images”: Check the image names and tags, and that the images can be pulled with the connection’s credentials (or anonymously for a public connection).
No images discovered: For public connections, confirm each listed image exists and that an omitted tag has a latest tag. For credentialed catalog scans, confirm the account can list at least one tagged repository.
Only one connection per registry URL: Each registry URL can be connected once per organization. Connecting the same URL again updates the existing connection; to change credentials, edit the existing connection.