Managing shared scan credentials

Shared scan credentials allow you to authenticate multiple sites using the same credentials, reducing the need for repetitive configurations. It is also helpful when credentials change frequently. For example, if your organization’s security policy requires credentials to change every 90 days, you can apply changes to a shared credential to apply across all sites.

To configure shared credentials, you must have a Global Administrator role or a custom role with Manage Site permissions.

To compare shared and site-specific credentials, see Shared Credentials vs. Site-Specific Credentials.

Overview

This article covers the following steps:

1. Create a set of shared scan credentials
2. Restrict credentials
3. Test shared scan credentials
4. Assign shared credentials to sites
5. Verify scan credential authentication
6. Manage existing shared scan credentials

Create a set of shared scan credentials

1. From the Security Console, select Administration and under Scans, click Shared Credentials.
2. Click New.
3. Enter a name and description.
4. Click Account and select an authentication service.
5. Provide the required authentication details.
   • If you do not know what authentication service to select or what credentials to use for that service, consult your network administrator.
6. Optionally, restrict the credentials.
7. Optionally, test the credentials.
8. Click Save.

Restrict credentials

If a particular set of credentials is only intended for a specific asset or port, you can restrict the use of the credentials accordingly. This prevents scans from running unnecessarily longer due to authentication attempts on assets that don’t recognize the credentials. You can add multiple restrictions at once to a site.

If you restrict credentials to a specific asset or port, they are not used on other assets or ports and are excluded from all other scan targets.

Specifying a port allows you to limit your range of scanned ports in certain situations. For example, if you are scanning web applications using HTTP credentials, you can specify which assets to scan to avoid scanning all web services in the site.

1. Go to Administration > Shared Credentials.
2. Select an existing credential or create a new one.
3. Go to Restrictions.
4. Enter restrictions in the following formats:
   • Single IP address: for example 192.168.1.5
   • IP range: for example 10.1.1.1 - 10.1.1.50
   • CIDR: for example 172.16.0.0/16
   • Hostname: for example host.example.com
   • IPv6: for example 2001:db8::1, or 2001:db8::1 - 2001:db8::ff
5. Optionally, enter a port number.
6. Click Save.

Hostname restriction behavior

Hostname-based restrictions rely on DNS resolution. If the scan engine cannot resolve the hostname of the scanned asset, the credentials will not be used to safeguard against applying credentials without validation. For example, if a credential is restricted to rapid7.com and the IP address is set to 10.1.1.1, the credential won’t be supplied if DNS can’t resolve the IP address to rapid7.com.

Test shared scan credentials

You can verify that a target asset will authenticate a Scan Engine with the credentials you’ve entered. This is a quick method to ensure that the credentials are correct before you run the scan.

For shared scan credentials, a successful authentication test on a single asset does not guarantee successful authentication on all sites that use the credentials.

1. Go to Administration > Scans > Shared Credentials and select the credentials you wish to test.
2. Open the Account tab and expand Test Credentials.
3. Select a Scan Engine to test.
4. Enter target hostname or IP address.
5. To test authentication on a single port, enter a port number.
6. Click Test credentials

Assign credentials to sites

You can assign a set of shared credentials to one or more sites. Doing so makes them appear in lists of available credentials for those site configurations. Site Owners still have to enable the credentials in the site configurations. See Configuring scan credentials.

To assign shared credentials to sites:

1. From the Security Console, select Administration and under Scans, click Shared Credentials > Site assignment.
2. Select one of the following options:
   • Assign the credentials to all current and future sites.
   • Assign the credentials to selected sites only. If you select the second option, the Security Console displays a button for selecting sites.
   1. Click Select Sites.
   2. Select the sites you want to include, or select all.
   3. Click Add sites.
   4. Review selected sites on the Site Assignment page.
3. Configure other settings as needed, then click Save.

Verify scan credential authentication

1. Upon completion of a scan, go to Administration > Scans > History and select a Scan Name from the Past Scans table.
2. View the Completed Assets table and locate the asset you have added credentials to.
3. Look at the Authentication column for the located asset.
4. Review the Understanding credential authentication status section of this article for more information on what each status means.
5. For more details, click on the status.

Understand credential authentication status

In the Authentication column, the security console will display one of the following notes to determine the status of your credential authentication:

• Unknown: Credentials that do not return a success status or run a discovery scan.
• Partial Credential Success: Many different types of credentials were used, with one or more service being correct and one or more being incorrect.
• Credential Success: Correct credentials were provided for range of assets.
• Credential Failure: Incorrect credentials were provided for range of assets.
• No Credentials Used: No credentials provided for range of assets.
• No Credentials Supplied: A restriction prevented a credential from being used.

Edit shared scan credentials

While site-specific credentials can be edited from the Sites table, shared credentials must be edited by the Global Administrator from the Administration page.

To edit existing shared credentials:

1. From the Security Console, select Administration and under Scans, click Shared Credentials.
2. Click the name of the credentials that you want to change, or click Edit for that set of credentials.
3. Change the configuration as desired.