Connections Registry¶

Settings > Connections is persistent, versioned storage for the credentials and configuration you reuse across inspection runs - cloud accounts, repositories, container registries, Kubernetes clusters, and web applications. Save a connection once and tick it in the Run wizard instead of re-entering credentials every time.

Where to find it¶

In the left sidebar, open Settings > Connections. All Connections (/settings/connections/all) is one list of everything a scan can reach: each cloud account with the clusters and registries discovery saved under it, and the connections added by hand in a group of their own. There are also six categories, each with its own page:

Each page lists the saved connections for that category, one row each: the connection's name, how it signs in and what it points at, and how its last check went. The buttons at the end of a row are Check, Edit, the version history and Delete. A GCP cloud account has Discover in place of Check, because its check is a discovery.

Adding a connection¶

Every connection type and provider uses the same form, in the same order: a name, what to sign in with, what the type needs, then Check and Save.

1. Open the category page for the type you want (e.g. Settings > Connections > Cloud) and click the amber Add … Connection button. On All Connections, click Add connection and choose the type. In the Run wizard, Add in a section opens the same form in place.
2. If the type has several providers (cloud accounts have AWS/Azure/GCP; repositories have GitHub/GitLab/Bitbucket/Azure DevOps), pick a provider tab first - it resets the form to that provider's fields. A GCP cloud account has a few steps of its own, described under GCP: one key, then discovery.
3. Enter a Connection name (required) - a short human-readable name like "Production AWS".
4. Under Sign in with, give what the connection signs in with. A registry or a cluster can sign in with a saved cloud account instead of a credential of its own; see Signing in with a cloud account. Every other type signs in with its own credential:
   • AWS cloud account - the Role ARN. There is no secret to enter: the account is reached by role assumption only. On the hosted service the form has no editable External ID either: it shows your organization's platform-generated External ID and the trust-policy condition to add to the role (see Cloud Account Configuration).
   • Azure cloud account - Tenant ID, Client ID and the client secret.
   • Repository, web application, pentest target - a token, where one is needed.
   • Registry - a user name and a password or token. Leave both empty for a public registry.
   • Cluster - a kubeconfig file, or a secret reference to one.
5. Fill in the fields for the type (e.g. AWS: Account ID, Regions; Repository: Org/Owner, Repos; Registry: Registry, Repository, Tag; Cluster: Cluster Name, Context, Namespaces; Web App: Target URL, Auth Type; Pentest Target: URL, Standing Authorization Note). The fields map 1:1 onto the fields of a scan target. The ones set less often are under More options.
6. Click Check, then Save.

A repository or a web application can be grouped under a saved cloud account with Cloud account (optional) under More options. That only groups it under the account in the list. It does not sign in with the account.

Check, then Save¶

Check never saves. It tests the sign-in with what the form holds and tells you how it went. The form then reads Check passed or Check failed, with the reason for a failure. You can change the form and check again as often as you need.

Save runs the same test and stores the connection only when it passes. If the test fails, nothing is saved and the form says why. In the Run wizard the button reads Save and add to this scan, and the saved connection is ticked for the scan you are building.

Save without checking stores a new connection without the sign-in test. It is offered when you add a connection, not when you edit one. The connection is listed as Not checked until you check it. Use it when the credential cannot be tested from the console yet, for example a secret reference that is only readable at scan time. What you typed is still validated: a cluster needs its kubeconfig, a pentest target needs a public URL and its authorization note, and a registry needs a valid host.

Check on a saved connection's row tests the connection exactly as it is saved and updates its check status. A check made from the edit form with changes in it tells you about the changed form only: the row's status follows what is saved.

Checks are limited to 10 per minute per organisation unless your administrator changed it. Past that the form asks you to wait a minute.

Credential references vs. raw secrets¶

A credential can be the secret itself or a secret reference - accepted schemes are env://, vault://, aws_sm://, aws_ssm://, azure_kv://, gcp_sm://, and base64://. For example, env://GITHUB_TOKEN tells the platform to read the token from that environment variable at scan time. A file (a service-account key, a kubeconfig) is chosen with Choose file; Paste it, or use a secret reference instead switches to typing.

A credential is write-only. The console never shows it again: an edit form says that one is stored and leaves the field empty, and you replace it to rotate. Leave it empty to keep the stored one.

What the check status means¶

Every connection row, in Settings and in the Run wizard, carries one status:

Not checked is never a pass and never a failure. It means there is no result for the connection as it is saved now.

The status describes what is saved. Changing a connection's credential, its fields or its cloud account replaces the status: with Checked when the save tested the change, with Not checked otherwise. Renaming a connection or disabling it keeps the status.

A row also says how the connection signs in: "Signs in with Production GCP's service account", "Signs in with its own kubeconfig", "IAM role · account 123456789012", or "No sign-in" for a public registry or an open web application. A disabled connection is marked Disabled.

Signing in with a cloud account¶

A container registry or a Kubernetes cluster that lives in a cloud account you have already saved does not need a credential of its own. Under Sign in with, choose:

• A cloud account's service account - the connection signs in with the saved account. No password or kubeconfig is asked for.
• Its own credential - a user name and password or token for a registry (Docker Hub, GHCR, Harbor and others), a kubeconfig for a cluster.

A new registry or cluster starts on the cloud account when one is saved. When none is saved, the first choice is unavailable and says so: add a cloud account first.

A connection that signs in with an account brings that account into every scan that uses it, because the scan signs in as the account. The Run wizard shows this on the account's row.

A registry¶

With a GCP account, the form lists the Artifact Registry repositories the account can read, under Repositories this account can read. Check lists them (it runs a discovery of the account). Tick the ones to keep and click Save N selected. Each is saved as a connection of its own, named by its path, and is scanned as every tagged image in it; see How a registry becomes scan targets.

Type a registry and repository instead names one by hand:

If the form says the tag is required, either set one, or run a check of the cloud account so that it lists the repository.

With an AWS or Azure account, name the registry, repository and tag by hand. The scan signs in to the registry as the account. Check tests the account's own sign-in, which is the credential the scan will pull with.

Use Its own credential for a registry on any host that is not the cloud account's own.

Switching a saved registry from its own credential to a cloud account removes its saved password when you save. The form says so before you do.

A cluster¶

With a GCP account, the form lists the GKE clusters the account can see, under Clusters this account can see. Check lists them. Tick the ones to keep and click Save N selected. A cluster saved this way needs no kubeconfig: its address and certificate come from the check, not from you.

A cluster signs in with a cloud account only by being picked from that list. For an AWS or Azure account, or a cluster the list does not show, choose Its own credential and give a kubeconfig.

A kubeconfig that signs in through gcloud. A GKE kubeconfig normally calls gcloud to sign in, and a scan cannot run gcloud. Choose the kubeconfig under Its own credential, then pick the GCP account under Cloud account for gcloud sign-in. The scan uses that account's key in place of gcloud. The key is not uploaded a second time.

What cannot be changed on a discovered connection¶

A registry or cluster that was picked from a cloud account's list is named by what the check found: the registry host, project and repository, or the cluster's name, location and project. The edit form shows these read-only. To scan something else, pick it from the account's list. Its other fields, and its name, can be edited.

Editing and version history¶

Click a saved connection to open its edit form (same form as creation, pre-filled - except the credential field, which is always shown blank since the API never returns a stored secret value; leave it blank to keep the current credential).

Every create, edit, or restore writes a new version. Open the version history drawer (the history icon on a connection row) to see:

• A list of every version, with editor and relative timestamp (e.g. "3 hours ago").
• A diff pane for the selected version - added/removed/changed fields color-coded (green/red/amber), plus whether the credential changed (shown separately, since the actual secret value is never diffed).
• A "Show unchanged" toggle to include fields that didn't change in that version.
• A Restore this version button on any version that isn't the current one. Restoring doesn't delete history - it creates a new version carrying that older version's field values.

Saving an edit that changes the credential or the fields runs the sign-in test, as Save does on a new connection. A rename alone does not.

Restoring a version that passed its test when it was saved does not test it again, so a provider outage cannot block a rollback. A version that was never tested is tested before it is restored, and is not restored if the test fails. After a restore the connection reads Not checked unless the restore tested it.

GCP: one key, then discovery¶

A GCP cloud account needs one service-account key. Its Check is a discovery: it signs in with the key, tests each permission, and lists what the key can read - projects, GKE clusters and Artifact Registry repositories. You choose what to keep, then save. Each kept cluster and repository is saved as a connection under the account and uses the account's key, so no kubeconfig and no registry password is entered.

Discovery is available for GCP service-account connections and, described below, AWS role connections. See What is not covered yet.

Add the account: Sign in, Check, Choose, Save¶

Open Settings > Connections > Cloud, click the add button and choose GCP. The form shows its four steps at the top: 1 Sign in, 2 Check, 3 Choose, 4 Save.

1 Sign in.

2 Check. Click Check. A short-lived job signs in with the key, tests each permission and lists what the account can reach. It usually finishes within a minute. The Check result panel beside the form shows:

Each permission is marked OK or Missing, and a missing one names the role that grants it. A listing that could not be made is shown with the command that fixes it; see Could not list. The panel's verdict is Passed, Passed, 2 roles missing, Passed, needs attention or Failed. Fix what is missing in Google Cloud and click Check again; if you choose another key, check again to see what that key can reach.

One service account for many projects describes the roles and APIs the key needs.

3 Choose. Under Found: choose what to save with the account, tick what to keep:

• Projects - ticked means every project this account can read, including ones created later. Untick it, or use Pick projects, to keep only the projects you tick. See Include projects created later.
• GKE clusters - marked Reachable, or Private for a cluster with a private endpoint, which can be saved for later and cannot be scanned yet.
• Artifact Registry repositories - marked Readable. A repository of another format (npm, Maven, Python and so on) is marked Skipped and cannot be ticked. A repository whose address cannot be saved (see What is not covered yet) is marked Cannot be saved, says why, and cannot be ticked.

Everything that can be scanned starts ticked, so you untick what you do not want. A private-endpoint cluster starts unticked. A long list shows its first rows and a Show all button.

4 Save. Save connection and N selected saves the account, then one connection for each ticked cluster and repository. In the Run wizard the button also adds the account to the scan you are building.

Save without checking keeps the account only. Its clusters and registries can be added later with the same check.

If you leave the form without saving, nothing is kept: a key that was checked and never saved is discarded. Leaving while a save is in progress does not cancel that save. While the form stays open, a checked key is kept for 24 hours. After that the form says so and asks you to choose the key again.

Editing a saved account¶

Check on a saved account's form lists what the stored key can reach, as above, and you can save more of what it finds. To rotate the key, choose the new file and click Check: the form says Key accepted or Key refused. Save, then check again to list what the new key can reach.

Discover¶

The same result has a page of its own for a saved account: Settings > Connections > {account} > Discover (/settings/connections/discover?connection=<id>), which opens from the Discover button on a GCP row of the Cloud page or of All Connections.

Run discovery starts a short-lived job. The page shows Discovery is queued, then Discovery is running, and then the result. Nothing is scanned, and nothing is saved until you choose. A job that does not report back ends as The discovery failed or The discovery expired with a sentence saying why; Run discovery again starts another. One discovery runs per connection at a time.

The result is three checklists. Tick what to keep:

• Projects - each project is marked New or Already saved.
• GKE clusters - reached with the account's key. A cluster with a private endpoint is marked Cannot be scanned yet.
• Artifact Registry repositories - only Docker repositories can be ticked. A repository of another format (npm, Maven, Python and so on) is listed and marked Skipped. A Docker repository whose address cannot be saved is marked Cannot be saved, and its row says why. A kept repository is scanned as every tagged image a discovery lists in it, each at its newest tag. Single images cannot be picked from it.

A section that says "N not listed: name not accepted" found N projects, clusters or repositories whose name discovery does not accept. They exist in Google Cloud and are not in the list. In the registries section it can also count a location whose name was not accepted: that location's repositories are not listed, and the list is marked incomplete. A repository row can say the same of its images.

The save button, labelled with what is ticked ("Save 3 projects, 2 clusters, 1 registry"), records the selection: the account's project list, and one connection per ticked cluster and repository. Saving adds and updates. It never deletes: a cluster or repository you leave unticked later keeps its connection until you delete that connection. A discovered connection you renamed keeps its name, and one you gave a credential of its own is left alone. If another connection of the same type already has the name, that item is not saved and the page lists it; rename the other connection and save again.

If the connection's key or Organisation ID changed after the discovery ran, the page says the result is from the earlier key and cannot be saved from. Run discovery again.

Include projects created later¶

With Include projects created later ticked, every project the account can read is scanned, so individual projects cannot be left out. Untick it to pick projects.

The project list is not read from Google when a scan starts. It is taken from the connection's last successful discovery at the moment you add the connection to a scan in the Run wizard. When that discovery is more than 24 hours old, a new one is started in the background, and the scan you are building uses the list it already has. A project created in Google Cloud can therefore take up to 24 hours, or until you run discovery yourself, to appear in a newly built scan.

The list is fixed once the account is in a scan. A schedule, a repeated run and a resumed run keep the project list they were built with; they do not pick up later projects. To bring them up to date, run discovery and add the account to the schedule or scan again.

At most 1,000 discovered projects are added to a scan this way. The Run wizard says how many were discovered and added, how old the list is, and when more were found than it takes.

Could not list¶

A listing that failed is shown under Could not list, per section and, where it applies, per project. The rest of the result is still usable.

The command names the role or API, the service account and the organisation or project. Where the console cannot read one of those, it prints SERVICE_ACCOUNT_EMAIL or PROJECT_ID for you to replace; this is the case for the service account when the key is stored as a secret reference. Copy command copies it. The commands are yours to run: the product grants nothing itself and never runs them.

A list that stopped at a limit says so: "This list of ... is incomplete: the job stopped at its limit of projects, pages or time." See Limits.

Private-endpoint clusters¶

A GKE cluster whose control plane has no public endpoint cannot be scanned yet. It is not reachable from the deployment, and nothing you install changes that in this release. It can be ticked and saved: it is kept and listed, marked Cannot be scanned yet on the Discover page and Unavailable in the Run wizard, and it cannot be added to a scan.

How a registry becomes scan targets¶

A saved Artifact Registry repository is not one image. When you add it to a scan, it becomes one container-image target per tagged image in the repository. Single images cannot be picked from it:

• Each image is scanned at the tag of its newest version. When that version has several tags, latest is the last choice and the highest of the others in string order is used.
• An image whose newest version has no tag is skipped.
• At most 200 images are taken from one repository, in name order. The rest are skipped.
• The image list is the one the last discovery read, not a fresh listing. The wizard shows how many images were included, how many were skipped and why, and how old the list is. Run discovery on the account to refresh it; a list more than 24 hours old is also refreshed in the background. Like the project list, the images and tags are fixed when the repository is added to a scan: a schedule or a repeated run keeps scanning the tags it was built with.
• The images are pulled with the cloud account's key, so the account is added to the scan with the repository. The wizard shows this on the account's row, and the account leaves the scan again when you remove the last repository that needed it.

A repository cannot be added to a scan when the last discovery did not find it, could not list its images, or found no image with a tag. The wizard says which, and what to do.

Limits¶

One discovery reads at most:

When it is used:

A list that hits a limit is marked incomplete. An account that reaches more than 50 projects has the clusters and repositories of the first 50 listed only. A repository past the 100th has no image list and cannot be added to a scan as a repository; add its images as registry connections by hand.

What is not covered yet¶

• Azure and GitHub. Discovery lists what a GCP service account or an AWS role can reach. For the other providers, add each cluster, registry and repository as its own connection.
• Repositories whose ID contains a dot, with four exceptions. Google's own gcr.io, us.gcr.io, eu.gcr.io and asia.gcr.io repositories can be kept and scanned, each in the location Google creates it in (us, us, europe and asia); their images are pulled from the Artifact Registry address, and the row also shows the older address they are served at. Any other Docker repository with a dot in its ID, and one of the four names in any location other than its own, is listed, marked Cannot be saved and cannot be ticked. Add its images as registry connections by hand.
• Picking images per scan. A discovered repository always adds every tagged image it holds, up to the limit. To scan chosen images only, add them as registry connections by hand.
• Private-endpoint clusters. They are kept and listed, and cannot be scanned yet.
• Picking from an AWS or Azure account's list in the registry and cluster forms. A registry can sign in with an AWS or Azure account, but is named by hand there; a cluster can sign in with a cloud account only when it is picked from a GCP account's list. For an AWS account, choose its clusters and repositories in the account's own form (above).
• Folder-level commands. The grant command shown is for the organisation or for a project.

AWS: one role, then discovery¶

An AWS cloud account needs one role, and no access key: VirtualSutra assumes the role, with the External ID of your organization. Its Check is a discovery too: it assumes the role, tries each action, and lists what the role can reach - the accounts of your AWS Organization, EKS clusters and ECR repositories. You choose what to keep, then save. Each kept cluster and repository is saved as a connection under the account and signs in with the account's role, so no kubeconfig and no registry password is entered.

Add the account: Role, Check, Choose, Save¶

Open Settings > Connections > Cloud, click the add button and choose AWS. The form shows its four steps at the top: 1 Role, 2 Check, 3 Choose, 4 Save.

Click Check. A short-lived job assumes the role, tries each action and lists what it found. The Check result panel shows the role the job signed in as, each action that was refused with the commands that grant it, and the lists to choose from:

• Accounts. Every active account of the Organization the role can reach, ticked, and the hub account, which is always scanned. An account whose member role is missing is listed with the command that deploys the role to it (the StackSet); an account that is suspended or beyond the first 50 is listed and cannot be ticked. Accounts stays ticked to include accounts added later; untick it to pick accounts one by one.
• EKS clusters. Ticked, in each account and enabled region. A cluster whose endpoint is private is listed unticked and cannot be scanned yet. A public endpoint that accepts only some networks is ticked and says which: the scanner's address must be among them.
• ECR repositories. Ticked when the role can list their images and at least one carries a tag. A repository whose images could not be listed says why and cannot be ticked.

Every command shown is text for you to run, with the placeholders filled in. VirtualSutra grants nothing itself and runs none of them. If a Service Control Policy of your Organization denies an action, no role can be granted it.

Click Save connection and N selected. The account is saved first, then the ticked clusters and repositories, each as a connection under the account. Accounts you chose are added to the account's list of member accounts.

Scanning an Organization with a cluster in a member account¶

A cluster or repository in a member account is scanned through the account's role: the hub role is assumed first, then the member role, each with the External ID. An EKS cluster needs one more thing in the cluster itself: an access entry that maps the role to a read-only group, and the read-only ClusterRole bound to it. A scan that is refused says exactly which of the two is missing.

What is not covered yet¶

• Organizational units. Accounts are listed flat; the StackSet command targets the whole Organization.
• A custom endpoint (for example LocalStack). A connection with an endpoint URL cannot be discovered.
• AWS partitions other than the one your deployment runs in.

Azure: one service principal, then discovery¶

An Azure cloud account needs one service principal (an app registration in your Microsoft Entra tenant) with a client secret. Its Check is a discovery too: it signs in as the principal, tries each action, and lists what it can reach - the subscriptions, AKS clusters and ACR repositories. You choose what to keep, then save. Each kept cluster and repository is saved as a connection under the account and signs in with the account's service principal, so no kubeconfig and no registry password is entered.

Add the account: Sign in, Check, Choose, Save¶

Open Settings > Connections > Cloud, click the add button and choose Azure.

Click Check. The Check result panel shows the application the job signed in as, each action that was refused with the az command that grants it, and the lists to choose from:

• Subscriptions. Every subscription the principal can read, ticked. Subscriptions stays ticked to include subscriptions added later; untick it to pick one by one. A disabled subscription is listed and cannot be ticked.
• AKS clusters. Ticked when the cluster is integrated with Microsoft Entra and its API server is public. A cluster with local accounts only is listed as "needs Entra integration" and cannot be ticked. A private cluster is listed unticked and cannot be scanned yet. A public API server restricted to some IP ranges is ticked and says which: the scanner's address must be among them.
• ACR repositories. Ticked when the principal can list their images and at least one carries a tag. Listing needs the Container Registry Repository Catalog Lister and Repository Reader roles (a registry with repository-scoped permissions); pulling an image needs AcrPull on a default-mode registry. Which role lets the listing work on a default-mode registry is not verified: if Check refuses it, add the two roles or add the repository by hand.

Every command shown is text for you to run, with the placeholders filled in. VirtualSutra grants nothing itself and runs none of them. If an Azure Policy or a deny assignment blocks an action, no role assignment will grant it.

Click Save connection and N selected. The account is saved first, then the ticked clusters and repositories, each as a connection under the account. An account scans at most 50 subscriptions.

Scanning an AKS cluster¶

The scan checks that the cluster is the one that was discovered before it signs in. An AKS cluster needs one more thing inside it: the read-only ClusterRole, bound to the service principal's object ID (az ad sp show --id <client-id> --query id -o tsv). A scan that is refused says which of the roles is missing.

What is not covered yet¶

• Certificate or managed-identity sign-in. Only a client secret.
• Clusters with local accounts only, and private clusters.
• Management groups. Subscriptions are listed flat.
• Verification in the US Government and China clouds. They are supported by design but have not been tried against a live tenant.

Using a saved connection in a run¶

In the Run wizard's Targets step you tick what to scan. Each section - Cloud accounts, Kubernetes clusters, Container images, Repositories, Web applications - lists your saved connections of that type as rows with a checkbox. They are the rows of Settings > Connections: the same name, the same sign-in line and the same check status.

• Tick a row to add the connection to the scan. Untick it to take it out.
• Untick all in a section's heading takes out everything you ticked there.
• Show all appears when a section has more rows than it shows at first.
• This scan, at the foot of the step, counts what is ticked: projects, accounts, clusters, images, repositories and web applications.

Ticking a cloud account ticks everything found under it¶

Ticking a cloud account adds the account and every connection saved under it: the clusters and registries that sign in with it, and any repository or web application you grouped under it. You do not add them one at a time.

• The account's row says what came with it: how many clusters and registries, and how many repositories and web applications when there are any. Each cluster and registry row reads ticked with the account.
• Untick any row you do not want in this scan. The account and the rest stay.
• Unticking the account takes out everything its tick brought: the clusters and registries, and any repository or web application grouped under it. A connection you ticked yourself stays. When that is a registry that signs in with the account, the account stays too, as that registry's sign-in.
• A connection under the account that cannot be scanned is not ticked. It is listed, greyed out, with the reason; see below.
• The account is in the scan once, however many clusters and registries sign in with it.

A cloud account can also be in the scan without being ticked: when you tick only a registry that signs in with it. The account's checkbox then shows a dash, and its row says which registry it is there for. The account itself is scanned too. Tick it to bring in everything under it, or untick the registry to take the account out.

Rows that cannot be ticked¶

A row marked Unavailable is greyed out and cannot be ticked. It says why. The common cases:

A connection that has never been checked has a Check button on its row while it is unticked, so you can test it without leaving the wizard. A GCP cloud account is checked from its own form or its Discover page instead.

Options¶

Options on a row opens what can be set for this scan only: regions, namespaces, scanners and the connection's other optional fields. It is closed by default.

• A blank field keeps what is saved. The saved connection is never changed from here.
• Tick with these options adds the connection with what you set. On a row that is already ticked the button reads Apply to this scan.
• For a ticked row the panel also says which version of the saved connection is in the scan, which fields were set for this scan, and, for a repository, how many images are included and how old that list is.
• A repository that is scanned as every image in it has no tag or user name to set here: each image has its own.

A ticked connection is fixed to the version it had when you ticked it, so a later edit never silently changes a scan that already uses it. A saved schedule or a repeated run keeps what it was built with. Untick the row and tick it again to pick up a later change.

Add¶

Add in a section's heading opens the connection form in place, with the same Check and Save as Settings > Connections. Save and add to this scan saves the connection and ticks it. What you save here also appears under Settings > Connections and can be reused in every scan. Close shuts the form without saving.

If a connection is saved and cannot be added to the scan, the section says so and why. It stays in the list, unticked.

Targets that are not saved connections¶

• From an earlier run · read-only - a cloud account, cluster or image carried in from an earlier run or schedule that was entered by hand. It can stay or be removed, it cannot be edited in the wizard, and it is sent unchanged.
• Repositories on the hosted agent - with the Hosted agent scan runner, Type a repository for the hosted agent takes a repository whose token is read in your own environment, which a saved connection cannot hold.

The pentest wizard lists saved pentest targets as the same rows. One target is tested at a time, so ticking a row chooses it.