Git repository authentication

ScanSuite clones a private repository over SSH, with a key you give it. Public repositories clone over HTTPS without one. HTTPS addresses that contain a user name or password are refused.

Whose key is used

There are two keys: your own, under My account, and the team's, on the Teams page.

• If your own key cannot reach the repository, the scan fails; it does not fall back to the team key. The scan log names whose key was used.
• A scan keeps the key it started with, so replacing a key affects new scans only.

1. Generate a key

Create a key without a passphrase. A key protected by a passphrase is refused when you save it, for both kinds of key.

ssh-keygen -t ed25519 -f ./scansuite_deploy_key -N ""

Check: this prints the public key without asking for a passphrase.

ssh-keygen -y -P "" -f ./scansuite_deploy_key

2. Add the public key to the Git server

Check: from any machine that can reach the Git server, this lists the repository's branches:

GIT_SSH_COMMAND="ssh -i ./scansuite_deploy_key -o IdentitiesOnly=yes" git ls-remote git@<GIT_HOST>:<GROUP>/<REPO>.git

3. Store the private key in ScanSuite

The key must include its header and footer lines:

-----BEGIN OPENSSH PRIVATE KEY-----
...
-----END OPENSSH PRIVATE KEY-----

Your own key

For scans you start yourself. Nobody else can read or use it, administrators included.

1. 01
   Open My account and find the Repository access card
2. 02
   Paste the private key under SSH key for cloning
3. 03
   Click Save

Check: the heading shows Saved, with the date and the key's SHA256 fingerprint; Not set means no key is stored. Remove deletes it after the question Remove your SSH key? Scans that started with it will stop cloning.

The team key

For schedules, repository watches, pipeline scans and members without a key of their own. Team admins and operators set it.

1. 01
   Open Teams in the sidebar, then the Scanning tab
2. 02
   In the Team SSH key card, paste the private key into Private key
3. 03
   Click Save

zoom_inEnlarge

Check: the card shows that a key is saved, with its fingerprint. The key is stored encrypted and never shown again. Remove deletes it; scans that still use it stop using it at once.

4. Enter the repository in SSH form

On the Git Repository tab of the Static Analysis page, enter the SSH address. This is what tells ScanSuite to clone with a key:

git@<GIT_HOST>:<GROUP>/<REPO>.git

An ssh:// address works too. Full SSH and HTTPS addresses work for GitLab, GitHub and Bitbucket.

Check: while you type an SSH address and neither you nor your team has a key, the form warns SSH repositories need an SSH key for cloning, and neither you nor your team has set one, with links to My account and the team settings. The warning disappears once a key is saved. If you submit anyway, the scan is refused:

Repository names and the Git service

Short repository names and Bitbucket project keys, instead of full addresses, work only when the installation's Git service is Bitbucket:

• The Git service is one setting for the whole installation, on the System Settings page, Shared services tab, set by a system administrator: Service (GitLab, Bitbucket or GitHub), and for Bitbucket the Bitbucket address and the SSH clone address pattern with {project} and {repo} placeholders. It also decides how links to source lines are built. See System Settings.
• Your Git repository API key (My account → Repository access) is used only to list repositories when you submit a Bitbucket project or a repository name. It is never used to clone.

If the Git server's host key changes

The first time a scan connects to a Git server, the server's SSH host key is accepted and remembered. If that host key later changes, the clone is refused. Confirm with the Git server's administrators that the change was expected before you ask your ScanSuite operator to accept the new key; an unexplained change can mean the connection is being intercepted.