Host Keys

Secure SSH access in Snake CI pipelines.

Version requirements for the Host Keys feature:

  • add-on version: ≥ 1.0.0
  • runner version: ≥ 1.0.0

By default, to protect against a man-in-the-middle attack, SSH performs host key verification.

The only downside is that it requires the user to manually run the ssh-keyscan command line tool to ensure that the host key is valid and manually add host keys to the known_hosts file in the CI pipeline.

Starting from version 1.0.0 Snake CI simplifies this process by allowing you to manage known host keys directly from the Web interface.


Hosts keys can be set at three levels:

  • Global: AdministrationSNAKE CIHost Keys
  • Project: ProjectProject SettingsSNAKE CIHost Keys
  • Repository: RepositoryRepository SettingsSNAKE CIHost Keys

Host keys defined at the upper level are available at lower levels too.

Snake CI automatically adds the host key of your Bitbucket instance.


Adding new host key

To add a new host key, proceed to SNAKE CIHost Keys section in the Administration Panel or under Project / Repository settings and click on the Add Host Key button.

Enter the host name and the SSH port (22 is the default one) and click Scan.

Snake CI will try to resolve the SSH public key and its fingerprint automatically.

After a short delay you will see the host’s public key and fingerprint. Proceed to the next section and learn how to verify that the host key is the correct one.

In some cases, however, Snake CI will not be able to obtain the host key by itself. If you see an error message after clicking on the Scan button, consult the Manually retrieving SSH host key section to find out how to get the host key manually.

Verifying host key

If Snake CI is able to obtain the SSH host key for the given host automatically, you will see its fingerprint in the add dialog.

To validate that the retrieved SSH key is correct, you can use the ssh-keyscan and ssh-keygen tools.

Run the following command on your local machine and lookup for the fingerprint, which you see in the Snake CI Web interface:

  • Linux

    ssh-keyscan -t rsa,dsa,ecdsa,ed25519 -p <port> <hostname> 2>&- | ssh-keygen -lf -
    
  • Windows

    ssh-keyscan -t rsa,dsa,ecdsa,ed25519 -p <port> <hostname> 2>$null | ssh-keygen -lf -
    

If you’re unable to match the fingerprint that you see in the add dialog with the command above’s output, then double-check that <hostname> and <port> are correctly specified and exactly the same as in the add dialog and the ssh-keyscan command.

If you still see different fingerprints, then something fishy is might be going on. Contact your network administrator for more information.

Manually retrieving SSH host key

While Snake CI does its best to automatically obtain the SSH public key for the specified host, it may sometimes fail due to network problems, firewall rules, domain name resolution errors, or other reasons.

In this case, you will see a relevant error message and a prompt to input the public key manually.

You may click Rescan a couple of times to see if the problem will resolve by itself before proceeding to manually retrieving the host key.

To retrieve the specified server’s host key, run the ssh-keyscan command, copy output and paste into add dialog.

  • Linux

    ssh-keyscan -p <port> <hostname> 2>&-
    
  • Windows

    ssh-keyscan -p <port> <hostname> 2>$null
    

If the command doesn’t produce any output and you’re sure that <port> and <hostname> are correct, then the specified <hostname> might be reachable neither from your machine’s network nor from Bitbucket. Contact your network administrator for further guidance.

Troubleshooting

ssh <host>: Host key verification failed

Snake CI stores path to the generated known_hosts in the $CI_SSH_KNOWN_HOSTS_FILE environment variable.

To use known_hosts, which is automatically generated by Snake CI, provide GlobalKnownHostsFile option to ssh invocation with the path to known_hosts.

ssh -o GlobalKnownHostsFile=$CI_SSH_KNOWN_HOSTS_FILE <host> …

Last modified October 21, 2020