Scan images in your own registry

If your organization keeps container images in a registry of its own - Docker Hub, GitLab’s container registry, Harbor, or any other Docker Registry v2 server - Sencai can scan them for known vulnerabilities without you moving them. You connect the registry once, then press Test on an image to scan one tag or digest of it, or set a schedule so Sencai scans it again every day, every three days or every week.

This page is about registries you run or rent. Images in your organization’s own Sencai registry are scanned automatically when they are pushed - see Container registry.

What your registry has to look like

Sencai opens a connection to the address you type in, from the platform, on your behalf. To keep that safe the address has to meet these rules, and Sencai checks them when you save the registry and again on every connection:

It must be https://. Plain http:// is refused, so a token is never sent in clear text.
It must be served on port 443.
It must be a public address with an IPv4 address. Addresses in private networks (for example 10.x.x.x, 192.168.x.x), loopback, link-local and other reserved ranges are refused, and so are names that resolve to them. A registry that only has an IPv6 address cannot be reached.
It must present a certificate Sencai trusts. A self-signed certificate is reported as untrusted and the scan does not run.
It is the host only: no path, no query, and no user name or password inside the URL. Put credentials in the Username and Token fields. A URL without a scheme is read as https://.
Sencai’s own registry host cannot be added here. Use the Sencai tab of the registry for your own images.

A registry that is reachable only from inside your network or from a fixed list of addresses therefore cannot be scanned, and Sencai does not publish a fixed address to put on an allow-list. If the registry is on a private network, push the image to your Sencai registry instead.

docker.io and index.docker.io are saved as registry-1.docker.io, which is the host Docker Hub answers the registry API on.

Connect a registry and test the connection

Open Registry and choose the Custom Registries page (/gravity/registry/registries), then Add registry. Enter the URL, and if the registry needs a login a Username and a Token. Only an organization admin can add, change or remove a registry.

Test connection checks what the registry will let Sencai do and shows what it proved, check by check:

Check	What it means
URL is valid (https, port 443, public address)	The address passed the rules above
Registry reachable	The registry answered like a Docker Registry v2 server
TLS certificate verified	The certificate is trusted
Credential accepted	The registry accepted the stored login (or it answers anonymous requests)
Catalog readable	The registry lists its repositories. Many registries do not, and this is not an error: you can still scan an image whose name you type

A check the test could not reach is shown as not checked, never as passed. The headline is Connected, Authentication failed or Connection error, and a failed test says why:

Reason	What to do
The registry URL is not valid, or must use `https://`	Fix the address
Only registries on port 443 can be reached	Serve the registry API on 443
This address is not reachable from Sencai (private, internal or reserved network)	The registry has to be reachable from the public internet
The registry has no IPv4 address	Add an IPv4 address
The registry’s TLS certificate is not trusted	Use a certificate from a public authority
Could not connect to the registry / the registry did not answer in time	Check that it is up and that no firewall blocks the internet
The registry refused the stored credential	Replace the token
The stored token cannot be decrypted - save it again	Edit the registry and enter the token again
The registry is rate limiting us	Wait and test again

Connected means the registry answered and, if you gave a login, accepted it. It does not prove that the token may pull a particular image; a pull that is refused is reported by the scan itself. The result is remembered on the registry, so the list shows why the last test failed. Editing a registry’s URL, user name or token resets that result: a registry that you pointed at a wrong address is not shown as connected. To keep the stored token when you edit other fields, leave the token field empty. You can run up to 20 tests a minute.

The credential

The token you give Sencai is the only secret involved, and it is handled narrowly:

It is stored encrypted and is never shown again, in the app or by the API. Editing the registry with an empty token field keeps it.
It is used on the server side only. The browser never sees it: a scan request carries the repository and the reference, nothing else.
It is sent only to the registry host you entered and to the token service that registry names in its sign-in response, and only if that service passes the same address rules. A registry that tries to send Sencai to a private or internal address is refused, and the credential is not sent.
During a scan it is decrypted for that one scan, in an isolated scanner, and discarded when the scan ends. The scanner has no access to other organizations’ data or to the rest of the platform.
Every time Sencai uses it for a scan, the use is recorded in your audit log.

Create a token that can only pull from the registry. Sencai never needs to push, delete or administer anything, and a token with more rights than that only adds risk. A public image on Docker Hub needs no token at all.

Scan an image

Open the registry from Custom Registries.
Find the image’s card in the list and press Test. Under Browse by path you can instead look up a repository by its path, and press Scan on one of its tags.
In Scan an image, check the Repository, choose or type the Tag or digest (the tags the registry lists are offered as you type; sha256:<64 hex> scans one exact image), and optionally a Platform such as linux/amd64. Leave the platform empty to scan every platform of a multi-platform image, at most four.
Press Scan now.

The answer is Scan queued, not a result. The scan takes minutes: Sencai looks the image up, pins it to its digest, downloads its layers, and compares them with its vulnerability data. The list, the repository card and the scan page refresh by themselves every few seconds until everything has settled. A tag can move while you wait, so the scan is pinned to the digest the tag pointed at when the scan started, and the scan page shows it.

Download volume counts as a pull from your registry. If your registry rate limits pulls (Docker Hub does for anonymous users) or bills for transfer, a scan uses some of that.

The Scans section lists recent scans of the registry, each with its state, who asked and when. Open one to see the Platforms that were scanned and the Findings of the one you select. On the scan page:

Scan again starts a new scan of the same reference. It is unavailable while a scan of the same image is running.
Cancel scan stops a scan that has not finished.

What the states mean

Nothing here is shown as clean unless something was actually analyzed. A number that was not measured is shown as a dash, never as 0.

Status	Meaning
Queued — N ahead, Looking up the image in the registry…, Scanning…	Waiting or running
Waiting for vulnerability data	Scanning is paused because Sencai’s vulnerability data is missing or more than seven days old. Scans start by themselves when it is refreshed
Clean	The scan succeeded, found no vulnerabilities, and recognized the operating system or application packages - there was something to check
Counts such as 3 critical, 5 high	Vulnerabilities were found (Critical, High, Medium, Low, Unknown)
Scanned — no packages found, cannot confirm the image is clean	The scan succeeded but the image has no recognizable packages, for example a single static binary. This is not called clean
`<OS>` is end of life — results may be incomplete	The base operating system no longer receives security updates, so the counts are a minimum
Partially scanned (1 of 2 platforms)	Only some platforms of a multi-platform image have a finished scan. The request has no overall result
Too large to scan (limit …)	The compressed image is over the limit (3 GB at the moment). It is not scanned and does not use your monthly quota
Not a container image — not scanned	A Helm chart or another artifact
Scan failed (`<reason>`), retrying at `<time>`	A temporary problem; Sencai retries with growing delays
Scan failed — `<reason>`, Gave up after N attempts — `<reason>`	The scan ended. The reason is shown; Scan again starts a new one
Not scanned	No scan has been recorded for this image
Scan status unavailable	Sencai could not read the scan state just now. That is not the same as “not scanned”
External scanning is not enabled in this environment	The feature is switched off where you are. This never means the image is clean

The page also tells you when the scanner for external registries is not running, when it is waiting for vulnerability data, and when your organization is close to its monthly quota.

Findings and decisions

The Findings card of a scan lists what the selected platform’s scan found, the same way the Sencai registry does: Severity, CVE, Package, the version installed, the Fix version if there is one, and the Decision. A finding from a newer scan of the same image and reference that is gone shows as fixed in the newer digest.

Under Security → Vulnerabilities (/gravity/security/vulnerabilities) the switch at the top has a third source, External registries. It lists the findings of the latest finished scan of every image you scanned, with the registry in a column and the same severity chips. Its summary shows coverage beside the counts, for example “3 critical in 12 of 13 images - 1 not scanned”: an image that was never scanned, was too large, or whose last scan failed is counted as not covered, never as zero. A row from a registry you can no longer read is not silently dropped.

People with response access can record a decision on a finding: Accept the risk, Mark as false positive or Reopen, with a Reason (required for the first two) and, for an accepted risk, an optional expiry date. The decision applies to that vulnerability in that package of that image in that registry for every later scan, an expired decision stops applying, and every decision is recorded in the audit log. See Vulnerabilities.

When a scan finds critical or high vulnerabilities that the image did not have before, the people with access to security findings get a notification in the app. It is batched: at most one per image per hour, and only for findings that are new.

Scheduled scans

The Scheduled scans card on the registry page repeats a scan automatically. Add schedule asks for a repository, a tag or digest, an optional platform and how often: every day, every 3 days or every week. You can pause, resume, change the interval or delete a schedule.

A schedule scanning a tag looks the tag up again on every run, so a tag that moved is scanned as it is now. A schedule scanning a digest scans that one image each time.
A schedule counts against the same monthly quota as a scan you start yourself. When the quota is used up or the scanner is off, a due schedule does not start a scan, and the card says the last scheduled scan did not start and why.
If a scheduled scan fails, the person who created the schedule is told in the app, at most once a day, while they can still read scans of the organization.

Limits

The limits are the same for every organization and are counted by Sencai, not by your browser.

Limit	Value
Scan runs per organization per calendar month (UTC)	300 at the moment. A run is one platform of one image; it counts when it is created, a run that is too large to scan counts nothing, and the Scans section shows how much of the quota is used
Scans you can request	30 per hour per organization and 10 per hour per person
Scans that are waiting or running	20 per organization
Schedules	50 per organization, at most one per repository, reference and platform
Platforms scanned per request	4
Compressed image size	3 GB
Scanned at the same time	One scan per registry, and one per organization

A request over a limit is refused with a message that says which one and, for the monthly quota, when it resets. A platform beyond the remaining quota is not scanned; the request is then shown as partially scanned and says how many platforms were skipped.

What is and is not scanned

Scanned: the operating-system packages and the application dependencies Sencai can find in the image’s layers, compared with a vulnerability database that is refreshed regularly. Each finding belongs to an exact image digest.

Not scanned:

Images nobody asked about. Sencai scans only the repository and reference you choose, or that a schedule names. It does not crawl the registry.
Anything other than known vulnerabilities in packages: no secrets, no configuration issues, no licenses, no malware.
Containers running on your servers. A scan looks at an image in a registry, not at what runs. See Vulnerabilities for scanning of running instances.
Artifacts that are not container images, images over the size limit, and platforms past the fourth.
Registries that are not public (see the rules at the top of this page).

Between scans nothing changes: a result is true of the day it ran, and new vulnerabilities appear every day. Use a schedule if you want the picture kept current.

Who can do what

Permission	Lowest default role	What it allows
Read external scans (`git.external-scan:read`)	Viewer	See the scans, schedules and scan states of your registries
Create external scans (`git.external-scan:create`)	Member	Start and cancel scans
Manage external scans (`git.external-scan:manage`)	Admin	Create, change, pause and delete schedules
Read security findings (`security:read`)	Viewer	See severity counts and findings, and get the new-findings notifications
Respond to security findings (`security:respond`)	Member	Accept a risk or mark a false positive
Add, change or remove a registry, Test connection	Admin	Manage the registry connection itself

Roles, custom roles and per-member denies follow permissions in depth. A person without the permission to read findings still sees the state of a scan, but not its counts.

Records and retention

Testing a connection, starting or cancelling a scan, every use of the stored credential for a scan, creating, changing or deleting a schedule, and every decision on a finding are recorded in your audit log. A registry address that Sencai refuses is recorded too.

Findings of a scan that a newer finished scan of the same image and reference has replaced are removed after 180 days, and scan records are removed after a year. If you delete the organization, its scans, findings, schedules and decisions are deleted with it.

When a scan does not work

What you see	What to do
This address is not reachable from Sencai	The registry’s address resolves to a private network. Scanning needs a public address
Repository or tag not found in the registry	Check the repository path and the tag. Docker Hub official images live under `library/`, for example `library/alpine`
The registry refused the stored credential	The token expired or lacks pull rights on that repository. Replace it
The manifest is larger than 4 MiB / returned something that is not an image manifest / content that does not match its digest	The registry is misbehaving or the reference is not an image. Sencai does not scan it
Too large to scan	Split the image or scan a smaller one. Sencai will not scan it
The organization’s monthly scan quota is used up	The quota resets at the start of the next month (UTC)
A scan of this image is already running	Open the running scan; there is a link in the message
External scanning is not enabled in this environment	Not an image problem; the feature is off where you are

What’s next

Container registry - your organization’s own registry, where every push is scanned and signed
Vulnerabilities - findings from all sources and how to triage them
Permissions in depth - how the keys above combine with custom roles
Audit log - where scans and decisions are recorded