In order for Sandfly to login to a remote host, it must have a working SSH credential. Sandfly can use four SSH credential types:

1. Username and password
2. SSH private key and optional password
3. Generated key
4. External credential provider

Account Requirements

In order for Sandfly to run correctly, it will need an account that can access root level privileges. Superuser root credentials are needed because Sandfly looks into the operating system in areas where normal users cannot access.

You can have Sandfly login as root, but many systems do not allow this. Instead, set up an account that has sudo privileges for use by this application. Sandfly is able to login and determine if it needs sudo to run. If so, it will use sudo and if it has proper permissions it will run normally.

Credentials View

Clicking on Credentials under the Configuration sub-section of the sidebar will take you to the credentials view.

All registered credentials will be displayed in the table. The view will be empty if no credentials have been created.

Username and Password

❗️

IMPORTANT: Username and Password SSH Authentication is Dangerous!

We do not recommend username/password SSH authentication unless you have no other options. If the remote system is compromised, logging in with a username and password allows the attacker to steal your credentials and use them elsewhere.

To protect against this risk, we only recommend you use SSH public key authentication as outlined in the next section.

If you want Sandfly to use a username/password you can select that option in the form, shown below.

The fields in the above image mean the following:

Credential Type - Select the Username/Password option.

Name - A human readable label that Sandfly uses to refer to this credential. For example, "webservers" could be used to associate that the credential is used to access web systems. This text field can only contain numbers, letters, spaces, hyphens and underscores (_) characters.

🚧

CAUTION: Lowercase, Numbers And Underscore Only

In label fields in Sandfly, you can only use lowercase letters, numbers, and the underscore (_). This naming style is also known as snake_case.

Username - The username you want Sandfly to use to login to the remote host. This must be a legal Linux username.

Password - The password to use for this user. This also assumes that the same password is used for sudo access if needed.

❗️

IMPORTANT: Sudo Password Should Match User Password

Sandfly assumes the user's login password will also be the sudo password if needed. If no sudo password is needed by this user, Sandfly will figure that out and not use it.

After you enter these values, click on the Finish button. Sandfly takes the data you enter, public key encrypts it, and stores it. Once added, you cannot read the credentials again. Credentials can only be read by scanning nodes when ordered to by the Server.

SSH Private Key and SSH Certificates

The process for adding an external SSH private key is largely identical to that for username and passwords. You can use a basic SSH private key, or use a private key and SSH certificate. Optionally, if the key is encrypted, you can enter the decryption password as well.

The fields in the above image mean the following:

Credential Type - Select the SSH Private Key option.

Name - A human readable label that Sandfly uses to refer to this credential. For example, "production_fleet" could be used to associate that the credential is used to access production systems. This text field can only contain numbers, letters, spaces, hyphens and underscores (_) characters.

🚧

CAUTION: Lowercase, Numbers And Underscore Only

In label fields in Sandfly, you can only use lowercase letters, numbers, and the underscore (_). This naming style is also known as snake_case.

Username - The username you want Sandfly to use to login to the remote host. This must be a legal Linux username.

Private Key - The SSH private key in standard SSH key export format.

SSH Key Passphrase (optional) - The password used to decrypt the SSH private key if one was used.

Key Certificate (optional) - The SSH certificate that matches the private key as signed by your SSH Certificate Authority (CA). We recommend users utilize a SSH CA where possible.

Sudo Password (optional) - The sudo password for this user if one is needed. If supplied, Sandfly will use this password to obtain root privileges.

Again, after you enter these values, click on the Finish button. Sandfly takes the data you enter, public key encrypts it, and stores it. Once added, you cannot read the credentials again. Credentials can only be read by scanning nodes when ordered to by the Server.

Generate SSH Key

A SSH key can be generated via the user interface for use as a credential. Three SSH key types are currently supported:

• ed25519
• RSA 4096 bits
• RSA 8192 bits

The process for adding a generated key is largely identical to that for the username / password option.

The fields in the above image mean the following:

Credential Type - Select your preferred SSH key type from one of the Generate options.

Name - A human readable label that Sandfly uses to refer to this credential. For example, "Cloud Systems" could be used to associate that the credential is used to access cloud-based hosts. This text field can only contain numbers, letters, spaces, hyphens and underscores (_) characters.

🚧

CAUTION: Lowercase, Numbers And Underscore Only

In label fields in Sandfly, you can only use lowercase letters, numbers, and the underscore (_). This naming style is also known as snake_case.

Username - The username you want Sandfly to use to login to the remote host. This must be a legal Linux username.

Sudo Password (optional) - The sudo password for this user if one is needed. If supplied, Sandfly will use this password to obtain root privileges.

Again, after you enter these values, click on the Finish button. Sandfly takes the data you enter, public key encrypts it, and stores it. Once added, you cannot read the credentials again. Credentials can only be read by scanning nodes when ordered to by the Server.

Finally, for any successfully generated key, the public key is provided on the Credential view or details page where it can be copied via the Copy button at any later point in time.

External Credential Provider

The steps for adding an external credential provider involves the completion of the form. The following fields are provided:

Credential Type - Select the External Credential Provider option.

Name - A human readable label that Sandfly uses to refer to this credential. For example, "production_fleet" could be used to associate that the credential is used to access production systems. This text field can only contain numbers, letters, spaces, hyphens and underscores (_) characters.

🚧

CAUTION: Lowercase, Numbers And Underscore Only

In label fields in Sandfly, you can only use lowercase letters, numbers, and the underscore (_). This naming style is also known as snake_case.

URL of external credential adapter service - The value must be a valid URL.

Make unique credential request per host - The option to make a unique credential request per host.

External credential service extra data (optional) - Provide any additional options that may be needed for the external service.

External credential service root CA certificate (optional) - The root CA certificate for the external service.

Again, after filling in the necessary fields, click on the Finish button to save the credential.

Refer to the External Credential Provider Interface documentation for full details about this option.