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 Platforms

The Scan Assistant supports the following platforms.

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

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.

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.

  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="PEM"
  • In PowerShell, navigate to your msi and enter: msiexec /i ScanAssistantInstaller.msi CLIENT_CERTIFICATE=`"PEM`"
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 and Scan Assistant Software Updates

In the Scan Assistant template, you can automatically rotate your Scan Assistant certificates and apply the most recent updates. Authentication is required for successful certificate rotation and automatic updates.

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

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. From the Administration tab, under Templates, click Create.
  2. To automatically rotate your Scan Assistant certificates, select the Rotate Certificates checkbox.
  3. To automatically apply the latest updates, select the Apply Updates checkbox.
  4. Click Save.

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