Using the Scan Assistant

The Scan Assistant achieves the same results as a credential scan without the need for administrative credential management and provides accurate, granular vulnerability fingerprinting and assessment for assets. The Scan Assistant allows the Scan Engine to connect directly to an endpoint in order to collect data without the need for additional credentials. A secure connection is created between the Scan Engine and the Scan Assistant by using elliptic curve asymmetric encryption (ECDSA) and advanced encryption standard (AES).

Once installed, the Scan Assistant provides Registry and File System services on the local asset and only runs when scans are performed.

The Scan Assistant Workflow

Supported Windows Platforms

The Scan Assistant supports the following platforms.

  • Windows 7
  • Windows 7 SP1
  • Windows 8.1
  • Windows 10
  • Windows 11
  • Windows Server 2008 R2
  • Windows Server 2008 R2 SP1
  • Windows Server 2012
  • Windows Server 2012 R2
  • Windows Server 2016
  • Windows Server 2019
  • Windows Server 2022

Resource Utilization

The Scan Assistant will occupy approximately 20MB in memory. It will consume 0% CPU when idle. CPU utilization can range from 2.5% to 6% when the Scan Assistant is active, for a duration of 60 to 120 seconds while a scan is completed.

NOTE

This guidance applies to Vulnerability scans, on systems that are at a reasonable patch level.

Why should I use the Scan Assistant?

The Scan Assistant provides a more secure way to scan your assets, removes the need for administrative credential management, consumes much fewer resources, and significantly decreases the time to complete for policy scans.

Better Security

The Scan Assistant leverages Transport Layer Security (TLS) with elliptic curve asymmetric encryption (ECDSA) and advanced encryption standard (AES) and digital certificates to create a trusted secure channel between the Scan Engine and the Scan Assistant.

No Credential Management

The Scan Assistant provides the only access needed for you to run an authenticated scan. There is no need for privileged Admin account access to assets. This means that the Scan Assistant can perform scans without the hassle of managing credentials to assets.

You should not use Windows credentials alongside the Scan Assistant, since the Scan Assistant acts as your ‘credential type’. Using both at the same time negates the Scan Assistant’s benefits.

Efficiency

The Scan Assistant is lightweight and efficient. It consumes minimal memory and CPU resources. Once installed, the Scan Assistant provides Registry and File System services on the local asset. The Scan Assistant only runs when scans are initiated.

Faster Policy Scans

Due to the large amounts of data being collected, policy scans usually take a while to complete. With the Scan Assistant, policy scan time completion improves vastly.

When Should I Use the Scan Assistant?

The Scan Assistant provides an additional tool that Nexpose and InsightVM administrators can leverage to expand and extend enterprise vulnerability coverage. It is complementary to the Insight Agent, and compatible with the InsightVM cloud platform, but does not require cloud connectivity. The Scan Assistant provides an ideal solution for the following vulnerability coverage scenarios:

ScenarioHow the Scan Assistant Helps
Authenticated scan credentials are difficult to administer.The Scan Assistant uses digital certificates instead of traditional administrative credentials.
Need more control over site parameters.The Scan Assistant does not require Internet connectivity.
Concerns about agent resource utilization for mission critical assets.The Scan Assistant is only active during scans initiated by the Scan Engine.
Need granular control over assessment parameters for particular assets.The Scan Assistant responds to specific scan parameters defined by the Console to the Scan Engine.
Need to accelerate completion times for vulnerability and policy scans.Compared to traditional authenticated scans, the Scan Assistant will be faster for vulnerability scans and orders of magnitude faster for policy scans.

Scan Assistant Deployment Overview

To setup the Scan Assistant, perform the following steps:

  1. Download the Scan Assistant software (.MSI) and the Checksum (SHA512 file).
  2. Create and deploy X.509 digital certificates, that will be used to establish a trusted connection between the Scan Engine and scanned assets:
    1. A Public Key (PEM) is added with the Scan Assistant software and to all supported target assets as part of the installation.
      1. Microsoft Standard Installer (Msiexec.exe) is used to install the Scan Assistant software .MSI and one line PEM file with the /i command line parameter. Additional command line parameters can be seen by running Msiexec.exe, or found in Microsoft’s documentation. This information may prove useful in creating automated installation scripts.
    2. A Private Key(included in a PKCS12 file) is added to the Security Console as a scan credential.
  3. Configure and schedule scans for Sites with assets that have the Scan Assistant installed.

Scan Assistant

When the Scan Assistant is present, it is no longer necessary to conduct traditional WMI or CIFS credentialed scans of the same assets.

During a scan, a Scan Engine with access to the private key (scan credential) will authenticate to an asset running Scan Assistant with the public certificate. The Scan Engine communicates with the Scan Assistant using TLSv1.2 and connects to port 21047 (TCP) on each asset.

Asset Configuration Details

When installed, the Scan Assistant automatically configures the required parameters on the asset. It adds itself as a service that starts automatically and adds itself to the Windows firewall, listening on TCP port 21047. It also adds itself as an event source to the Windows eventlog and supports audit logging when required. When uninstalled, the Scan Assistant removes all changes made to the asset.

The following table shows additional Windows asset configuration.

ItemDetails
Process NameScanAssistant.exe
Default Installation PathC:\Program Files\Rapid7\InsightVM\ScanAssistant
Registry ConfigurationHKLM\SOFTWARE\Rapid7\InsightVM\ScanAssistant
Service Display NameRapid7 Scan Assistant
Service NameR7ScanAssistant
Service Listener Port21047 TCP
Service Registry ConfigurationHKLM\SYSTEM\CurrentControlSet\Services\R7ScanAssistant
Enable Enhanced Application Logging (set value to 1)HKEY_LOCAL_MACHINE\SOFTWARE\Rapid7\InsightVM\ScanAssistant\Debug

Asset deployment Notes

When the Scan Assistant is used, the following configurations and services that may have been required on the target Windows assets to enable traditional credentialed scans are no longer needed:

  • Remote access to an Administrative account
  • Remote access to built-in Windows services
  • Enable the Windows Registry services
  • Enable the WMI service
  • Enable the WinRM service
  • Enable File & Print sharing, or equivalent services

Installing the Scan Assistant

1. Download the Windows Installer and Checksum

Before setting up the Scan Assistant, you must download the MSI and checksum. The Scan Assistant currently only supports Windows installs.

2. Add port to Service Discovery and Asset Discovery

You must add TCP port 21047 to both Service Discovery and Asset Discovery for all scan templates before setting up the Scan Assistant.

3. Generate the Scan Assistant Credentials

You can automatically generate the Scan Assistant credentials in the InsightVM Console. When generating new Scan Assistant credentials, previous credentials are not automatically deleted. You can set up automatic certificate rotation or delete your old credentials.

Do not use Windows credentials with the Scan Assistant

Windows credentials should not be used alongside the Scan Assistant. The Scan Assistant acts as your ‘credential type’. Using both at the same time negates the Scan Assistant’s benefits.

  1. From the Administration tab, under Shared Credentials, click Create.
  2. On the General tab, enter a unique name and description.
  3. On the Account tab, in the Service field, select Scan Assistant.
  4. Select the Generate checkbox. By selecting this checkbox, your scan credentials are automatically generated once the credential is saved.
  5. On the Site Assignment tab, specify what sites can use the credential.
    • To allow all sites to access the credential, select Assign these credentials to all current and future sites.
    • To select a specific set of sites to access the credential, click Select Sites, select the sites you want to allow to use the credential, and click Add Sites.
  6. Click Save. You are redirected back to the Administration page.
  7. Under Shared Credentials, click manage.
  8. Click Edit on your newly created Scan Assistant shared credential.
  9. Copy the automatically generated PEM file.

4. Install the Scan Assistant on Windows

1. Deploy to an asset

Depending on your preferred tool, enter one of the following where PEM is the one-line PEM you generated in the previous step:

  • In the command prompt, navigate to your msi and enter: msiexec /i ScanAssistantInstaller.msi CLIENT_CERTIFICATE="-----BEGIN CERTIFICATE----- ... -----END CERTIFICATE----- "
  • In PowerShell, navigate to your msi and enter: msiexec /i ScanAssistantInstaller.msi CLIENT_CERTIFICATE="-----BEGIN CERTIFICATE----- ... -----END CERTIFICATE----- "
2. Verify the installer digital signature

To verify that the digital signature on the Scan Assistant Installer is valid, right-click on the installer and click Properties > Digital Signatures. The name of the signature should be Rapid7 LLC.

The Scan Assistant Installer Digital Signature

Automatic Certificate Rotation

In the Scan Assistant template, you can automatically rotate your Scan Assistant certificate.. When you enable certificate rotation, InsightVM automatically attempts to update the Scan Assistant to use the available credential with the latest expiration date.

You can not explicitly set the expiration date for certificates that are automatically generated from the Security Console. The default validity period for certificates is three years, so the most recent certificate added will have the longest validity period. To enable the certificate rotation, you will need to create a new certificate pair from the Security Console according to your IT Security policy for digital certificate or credential rotation.

Authentication is required

Authentication is required for successful certificate updates.

Do not remove the previous credential

To avoid a lock out, do not remove the previous credential until the certificate rotation is complete.

Rapid7 recommends deleting the oldest certificate every 3rd new certificate. Keep in mind that this recommendation is not necessarily the timeframe but in accordance with your internal certificate rotation policy.. The frequency of rotation is usually set by your IT Security Policy. You may choose to rotate the certificates in accordance with your Security Policy before they expire.

Certificate Rotation Workflow

Scan Assistant Software Updates

When you enable automatic updates, InsightVM updates the Scan Assistant with the latest installation, when available. Automatic updates are available for the Scan Assistant versions 1.1.0 and later.

  1. Select the Administration tab
  2. Under Templates, click Create.
  3. Select the Rotate Certificates checkbox, to automatically rotate your Scan Assistant certificates.
  4. Select the Apply Updates checkbox, to automatically apply the latest updates.
  5. Click Save.

For optimal scan performance with the Scan Assistant, Rapid7 recommends selecting either the Automatic Certificate Rotation or the Scan Assistant Software Updates feature, but not both in the same scan template. Enabling both features in the same scan template affects the scan performance issues when a Scan Assistant update or Credential rotation occurs.

Frequently Asked Questions

Can I manually generate the Scan Assistant certificate?

Yes. You can manually generate the Scan Assistant certificate on Linux or Windows.

Create the Scan Assistant certificate on Linux
1. Create the keys
  1. Open the command prompt.
  2. Create the private key.
    • For an ECDSA key, enter: openssl ecparam -out scan-assistant.key -name secp384r1 -genkey
    • For an RSA key, enter: openssl genrsa -out scan-assistant.key 3072
  3. Create the public key. Enter: openssl req -new -nodes -x509 -out scan-assistant.pem -key scan-assistant.key -days 3650 -subj "/O=/OU=/CN=scan.assistant.rapid7.com/emailAddress="
  4. Wrap the keys. Enter: openssl pkcs12 -export -inkey scan-assistant.key -in scan-assistant.pem -out scan-assistant.p12
  5. Add a password to further encrypt your file.
2. Add credentials to the console
  1. From your InsightVM console, click on the site that you want to enable the Scan Assistant.
  2. Click Authentication > Add Credentials.
  3. Add a name and description.
  4. Click Account.
  5. In the Service Type field, select Scan Assistant.
  6. In the PKCS#12 File field, select the p12 file.
  7. Enter your file password.
  8. Click Create.
  9. Click Save.
3. Create a single-line PEM
  1. In the command prompt, enter: cat scan-assistant.pem | xargs
  2. Copy the one-line PEM.
Create the Scan Assistant certificate on Windows
1. Generate a self-signed certificate
  1. In PowerShell, create the private key.
    • For an ECDSA key, enter: New-SelfSignedCertificate -Subject "CN=scan.assistant.rapid7.com/emailAddress=" -KeyAlgorithm ECDSA_secp384r1
    • For an RSA key, enter: New-SelfSignedCertificate -Subject "CN=scan.assistant.rapid7.com/emailAddress=" -KeyAlgorithm RSA -KeyLength 3072

Add dates to your certificate

If you want to specify the start and expiration dates of your certificate, add any of the following to your key in combination with -NotAfter and -NotBefore: *(Get-Date).AddDays

  • (Get-Date).AddMonths

    • (Get-Date).AddYears

    For example, New-SelfSignedCertificate -Subject "CN=scan.assistant.rapid7.com/emailAddress=" -KeyAlgorithm RSA -KeyLength 3072 -NotBefore (Get-Date).AddMonths(1) -NotAfter (Get-Date).AddMonths(121).

  1. Copy the generated thumbprint.
2. Export the PFX file

In PowerShell, run as administrator and enter:

1
$mypassword = ConvertTo-SecureString -String "PASSWORD" -Force -AsPlainText
2
Export-PfxCertificate -Cert Cert:\LocalMachine\My\THUMBPRINT -FilePath scan-assistant.pfx -Password $mypassword

Where PASSWORD is your password for the PFX file and THUMBPRINT is the thumbprint you created in step 1.

3. Add credentials to the console

Do not use Windows credentials with the Scan Assistant

Windows credentials should not be used alongside the Scan Assistant. The Scan Assistant acts as your ‘credential type’. Using both at the same time negates the Scan Assistant’s benefits.

  1. From your InsightVM console, click on the site that you want to enable the Scan Assistant.
  2. Click Authentication > Add Credentials.
  3. Add a name and description.
  4. Click Account.
  5. In the Service Type field, select Scan Assistant.
  6. In the PKCS#12 File field, select the PFX file.
  7. Enter your file password.
  8. Click Create.
  9. Click Save.
4. Extract the one-line public certificate (PEM file)
  1. In PowerShell, run as administrator and enter:
1
$oMachineCert=Get-Item Cert:\LocalMachine\My\THUMBPRINT
2
$InsertLineBreaks=0
3
$oPem=new-object System.Text.StringBuilder
4
$oPem.Append("-----BEGIN CERTIFICATE----- ")
5
$oPem.Append([System.Convert]::ToBase64String($oMachineCert.RawData, $InsertLineBreaks))
6
$oPem.Append(" -----END CERTIFICATE-----")
7
$oPem.ToString()

Where THUMBPRINT is the thumbprint you generated in step 1.

  1. Copy the one-line PEM.
How can I delete a certificate on Windows?

If you need to delete a certificate from the Windows certificate store, run the following in PowerShell:

1
Remove-Item -Path cert:\LocalMachine\My\581C1CA18731790790CF7392DC3510CFA5382BBD -DeleteKey
2
3
Remove-Item -Path cert:\LocalMachine\My\THUMBPRINT -DeleteKey
How can I verify that the Scan Assistant is present and running on the asset?

There are multiple ways to verify that the Scan Assistant is successfully installed on an asset.

Verifying the Scan Assistant is Listed as a Running Process

The Scan Assistant should be listed as a running process in the Task Manager.

  1. Open the Task Manager.
  2. Click on the Processes tab.
  3. Under the Name column click on the Scan Assistant dropdown.
    • You should see the Rapid7 Scan Assistant listed under the Scan Assistant dropdown.
Checking for the Rapid7 Scan Assistant in the Windows Services

The Rapid7 Scan Assistant should be listed in the Windows Services.

  1. Open Services > Extended tab.
  2. Under the Name column look for the Rapid7 Scan Assistant.
Viewing the Scan Assistant Public Certificate in the Windows Registry

The Scan Assistant public certificate should be viewable in the Windows Registry. Also, Debug level logging for the Scan Assistant is enabled by setting the Debug registry value at 1.

  1. Open the Registry Editor.
  2. Click on Software > Rapid7 > InsightVm.
  3. Open the ScanAssistant folder.
  4. In the Name column verify the Client Certificate is listed.
Validate whether an error is recorded in the Windows Application Event Log

If the client certificate is unable to load, an error is recorded in the Windows Application Event Log.

  1. Open the Event Viewer.
  2. Click the Windows Log Folder dropdown.
  3. Select Applications.
  4. In the Level column verify if an Error is listed.
Utilizing the Windows netstat-a command

The Windows netstat-a command can be issued from the Command Prompt to verify that the Scan Assistant is listening on TCP port 21407.

  1. Open the Command Prompt.
  2. Enter the netstat-a command:
    • \>netstat -a
What if I am unable to verify that the Scan Assistant is Installed

If you cant not verify that the Scan Assistant is successfully installed, ensure that you followed the installation steps correctly or contact your CSM for support.

How can I verify that the Network Scans can complete successfully?

There are two methods to verify that the Network Scans are able to successfully complete.

  • Check that all Scan Templates being used to assess assets with the Scan Assistant include TCP port 21047 for both Service Discovery and Asset Discovery.

  • Check that any network firewalls that may reside between Scan Engines and assets with the Scan Assistant installed have been configured to allow TCP port 21047.