Using SSH public key authentication

You can use Vulnerability Management to perform credentialed scans on assets that authenticate users with SSH public keys. This method, also known as asymmetric key encryption, involves the creation of two related keys, or large, random numbers:

• a public key that any entity can use to encrypt authentication information
• a private key that only trusted entities can use to decrypt the information encrypted by its paired public key

When generating a key pair, keep the following guidelines in mind:

• The application supports SSH protocol version 2 RSA, DSA, ECDSA, and Ed25519 keys.
  • RSA keys can range between 768 and 16384 bits.
  • DSA keys must be 1024 bits.
  • ECDSA keys must be 256, 384, or 521 bits.
  • Ed25519 keys are 256 bits and can not be altered.
• Keys must be in openssh-key-v1 format or in PEM format.

This article provides general steps for configuring an asset to accept public key authentication. For specific steps, consult the documentation for the particular system that you are using.

The ssh-keygen process will provide the option to enter a passphrase. It is recommended that you use a passphrase to protect the key if you plan to use the key elsewhere.

Generating a key pair

1. Run the ssh-keygen command to create the key pair, specifying a secure directory for storing the new file.

This example involves a 2048-bit RSA key and incorporates the /tmp directory, but you should use any directory that you trust to protect the file:

ssh-keygen -t rsa -b 2048 -f /tmp/id_rsa

This next example generates the key in PEM format:

ssh-keygen -t rsa -b 2048 -m PEM -f /tmp/id_rsa

This command generates the private key files, id_rsa, and the public key file, id_rsa.pub.

2. Make the public key available for the application on the target asset.
3. Make sure that the computer with which you are generating the key has a .ssh directory. If not, run the mkdir command to create it:

mkdir /home/[username]/.ssh

4. Copy the contents of the public key that you created by running the command in step 1. The file is in /tmp/id_rsa.pub file.

Append the contents on the target asset of the /tmp/id_rsa.pub file to the .ssh/authorized_keys file in the home directory of a user with the appropriate access-level permissions that are required for complete scan coverage.

cat /[directory]/id_rsa.pub >> /home/[username]/.ssh/authorized_keys

5. Provide the private key.

After you provide the private key, you must provide the application with SSH public key authentication.

Providing SSH public key authentication

If you want to add SSH credentials while configuring a new site, click the Create site button on the Home page.

OR

Click the Create tab at the top of the page and then select Site from the dropdown list.

If you want to add SSH credentials for an existing site, click that site’s Edit icon in the Sites table on the Home page.

1. In the Authentication tab of your site configuration, click Add Credentials.
2. In the Add Credentials form, enter a name and description for a new set of credentials if necessary.
3. Click Account under Add Credentials.
4. Select Secure Shell (SSH) Public Key from the Service dropdown list.

Be aware that this Secure Shell (SSH) Public Key authentication method is different from the method listed in the dropdown menu as Secure Shell (SSH). This latter method incorporates passwords instead of keys.

6. Enter the appropriate username for the target asset.
7. (Optional) Enter the Private key password used when generating the keys.
8. Confirm the private key password.
9. Copy the contents of that file into the PEM-format private key text box. The private key that you created is the /tmp/id_rsa file on the target asset.
10. (Optional) Elevate permissions to sudo or su. You can elevate permissions for both Secure Shell (SSH) and Secure Shell (SSH) Public Key services.
11. (Optional) Enter the appropriate user name. The permission elevation user needs to be set to root. To do this, the user’s permission elevation type needs to be set to sudo and the permission elevation user needs to be set as root.
12. The user name can be empty for sudo credentials. If you are using su credentials with no user name, the credentials will default to root as the user name.

If the SSH credential provided is a root credential, user ID = 0, the permission elevation credentials will be ignored, even if the root account has been renamed. The application will ignore the permission elevation credentials when any account, root or otherwise named, with user ID 0 is specified.

13. When you have finished configuring the credentials, click Create if it is a new set, or Save if it is a previously created set.

Providing user certificate-based SSH authentication

Using Vulnerability Management Console and Scan Engine versions released on or after October 15, 2025, you can authenticate to Linux and Unix assets using OpenSSH certificates, in addition to traditional username/password or SSH key methods.

User certificate-based SSH authentication provides a secure, scalable alternative to traditional SSH key management. This method integrates with your organization’s OpenSSH Certificate Authority (CA), automates expiration and revocation of SSH certificates, and supports frameworks like PCI DSS, NIST, and Zero Trust by enforcing identity-based authentication and minimizing long-lived credentials.

Supported certificate key types

The following OpenSSH certificate key types are supported:

• ssh-ed25519-cert-v01@openssh.com
• ssh-rsa-cert-v01@openssh.com

Configuring user certificate-based SSH authentication

You can configure user certificate-based SSH authentication either within a specific site configuration or centrally in Shared Credentials. Using Shared Credentials is recommended if multiple sites or scan configurations will use the same credential.

Example Configuration

Best Practices

When using user certificate-based SSH authentication with Rapid7, follow these best practices to keep your environment secure and your scans running smoothly:

Rotate certificates regularly

Replace SSH certificates on a routine schedule based on your organization’s PKI or security policy. Regular rotation helps prevent expired certificates from interrupting scans and reduces exposure if a certificate is compromised.

Configure Assets to trust the CA

Ensure scanned assets trust the relevant Certificate Authority (CA) that signs your SSH certificates so they can authenticate scan connections. If your organization rotates or changes the CA, update the trusted CA configuration on your assets to maintain connectivity.

Use short-lived certificates

Whenever possible, use certificates with short validity periods. Short-lived certificates minimize credential risk if a private key or certificate is exposed.