Using the Scan Assistant for Linux

Using the Scan Assistant for Linux

The Scan Assistant provides you with a secure alternative for authenticated scans that utilizes elliptic curve asymmetric encryption (ECDSA) and advanced encryption standard (AES) to form a trusted secure channel between the Scan Assistant and the Scan Engine. You can deploy the Scan Assistant with a public certificate in your environment which allows the Scan Engine to receive a private certificate.

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.

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:

Deployment environment

The controlled availability and early access release of the Scan Assistant for Linux is a Minimum Viable software prototype. It is only suitable for deployment to non-production environments and will not be upgradable.

Technical overview

The Scan Engine communicates with the Scan Assistant using TLSv1.2 with a 2-way client certificate authentication (will be upgraded to TLSv1.3 when applicable). The Scan Engine does not verify the Scan Assistant server side certificate. The Scan Assistant verifies the Scan Engine certificate (the Scan Engine is the client in this case). Essentially, we are using a 2-way client certificate authentication with a reversal 1-way methodology.

The Scan Engine needs to have access to the private key associated with the client certificate while the Scan Assistant must be deployed with the public key associated with the client certificate. This function of the Scan Engine solves a critical issue when private material is used, specifically clients should not know the confidential material required to access other clients and simplifies deployment since you only have to distribute one certificate instead of two. Furthermore, the Scan Assistant service generates a new server side certificate each time it starts which reduces the risk of a server side certificate compromise.

Scan Engine version

Scan Assistant for Linux Early Access Software requires your Scan Engine to be at 6.6.153 or higher.

Scan Assistant deployment overview

To setup the Scan Assistant, perform the following steps:

1. Download the Scan Assistant packages (.DEB or .RPM).

2. Create and deploy X.509 digital certificates, that will be used to establish a trusted connection between the Scan Engine and scanned assets.

A Public Key (PEM) is added with the Scan Assistant software and to all supported target assets as part of the installation. A Private Key (included in a PKCS12 file) is automatically added to the Security Console as a scan credential.

Standard Linux Package Managers for Debian (.DEB) or Red Hat Linux (.RPM) distributions are used to install the Scan Assistant software. Be certain to use the appropriate package for your Linux variant. A one line PEM file automatically generated via the Rapid7 Security Console will be pasted into the Scan Assistant config.json file in each scanned asset. Alternatively, the PEM file may be placed in the same directory as the config.json file.

3. Configure and schedule scans for Sites with assets that have the Scan Assistant installed.

Task 1: Download Scan Assistant for Linux

Early access to the Scan Assistant for Linux is available using the link provided in your welcome email.

Key file locations

• The Scan Assistant binary can be found at the following path: /user/sbin/ScanAssistant.
• The Scan Assistant configuration file (config.json) and asset one-line PEM file will reside in: /etc/rapid7/ScanAssistant.

Generate Scan Assistant credentials

The Scan Assistant leverages X.509 digital certificates, to establish a trusted connection between the Scan Engine and scanned assets.

Scan Assistant credentials can be generated automatically from the Security Console Shared Credentials interface. You can find more information on generating Scan Assistant credentials here . Also, you must copy the automatically generated PEM file for use with your Linux asset installation.

Task 2: Install the package

Scan Assistant packages are available for Debian (DEB) and Red Hat (RPM) based distributions.

DEB package installation

Debian based systems use the apt command to install DEB packages.

1. In the command prompt install sudo apt install ./R7ScanAssistant_1.2.1_amd64.deb.

2. Verify the following lines are in the output:

   YYYY/MM/DD HH:MM:SS Service action: “install” YYYY/MM/DD HH:MM:SS Service action: complete YYYY/MM/DD HH:MM:SS Service action: “start” YYYY/MM/DD HH:MM:SS Service action: complete

   If you are unable to see the output, the Scan Assistant may be installed but it is not running. Contact Support to receive assistance with this issue.

3. Enter sudo vi /etc/rapid7/ScanAssistant/config.json. The client certificate may optionally appear as a separate PEM file in the same directory. When using this method the PEM file must be named scan-assistant.pem. Insert the PEM formatted certificate into config file:

config.json 
{
 "ClientCertificate" : "(PEM formatted certificate)",
 "ResponseTimeout": 300,
 "Debug": false
 } 

4. Methods to verify the installation:

   • List installed packages
   • Enter apt list --installed | grep r7scanassistant
   • Check for service in memory status: ps -ef | grep ScanAssistant
   • Check syslog messages: grep ScanAssistant /var/log/syslog

The output should be similar to this: WARNING: apt does not have a stable CLI interface. Use with caution in scripts. r7scanassistant/now 1.2.1 amd64 [installed,local]

RPM package installation

Red Hat-based systems use the rpm command to install RPM packages

1. In the command prompt install sudo rpm -ivh R7ScanAssistant-1.2.2.x86_64.rpm.

2. Verify the following lines are in the output:

   YYYY/MM/DD HH:MM:SS Service action: “install” YYYY/MM/DD HH:MM:SS Service action: complete YYYY/MM/DD HH:MM:SS Service action: “start” YYYY/MM/DD HH:MM:SS Service action: complete

If you are unable to see the output, the Scan Assistant may be installed but it is not running. Contact Support to receive assistance with this issue. 3. Add the PEM certificate to configure the sudo vi /etc/rapid7/ScanAssistant/config.json file.

The client certificate may optionally appear as a separate PEM file in the same directory. When using this method the PEM file must be named scan-assistant.pem. Insert the following PEM formatted certificate into config file:

config.json
{ 
  "ClientCertificate" : "(PEM formatted certificate)",
  "ResponseTimeout": 300,
  "Debug": false
}

4. Methods to verify the installation:

   • List installed packages
   • Enter rpm -q R7ScanAssistant-1.2.1-1.x86_64 -i
   • Check for service in memory status: ps -ef | grep ScanAssistant
   • Check syslog messages: grep ScanAssistant /var/log/syslog

Name: R7ScanAssistant
Epoch: 0
Version: 1.2.1
Release: 1
Architecture: x86_64
Install Date: Mon 15 Aug 2022 05:31:15 PM UTC
Group:
Size: 9151866
License:
Signature: (none)
Source RPM: R7ScanAssistant-1.2.1-1.src.rpm
Build Date: Thu 11 Aug 2022 10:21:24 PM UTC
Build Host: AUS-MBP-6346
Relocations: (not relocatable)
Packager: Rapid7
Vendor: Rapid7
URL:
Summary: Rapid7 InsightVM Scan Assistant
Description: Rapid7 InsightVM Scan Assistant  

Tested Linux distributions

There are several Linux distributions that have been tested:

Linux distributions by service and init manager

Linux distributions by package manager