Install Ransomware Prevention

Ransomware Prevention is available to Managed Threat Complete (MTC) Ultimate and Managed Detection and Response (MDR) customers who have purchased the Ransomware Prevention add-on.

Ransomware Prevention is an add-on to your Insight Agent that provides Endpoint Prevention capabilities. Review the requirements for the Ransomware Prevention add-on.

Deployment options

There are two deployment options available for Ransomware Prevention:

Once you have decided which deployment option you will use, follow the instructions to install Ransomware Prevention as an add-on for your Insight Agent.

Option 1: Deploy using managed updates

If you have managed updates enabled for the organization you want to deploy Ransomware Prevention on, Rapid7 can deploy the add-on for you. To request that Rapid7 deploy Ransomware Prevention on your Insight Agent, create a support ticket for your Cybersecurity Advisor.

Option 2: Deploy using an installation package

If you have disabled managed updates for the organization you want to deploy Ransomware Prevention on, you must use the following instructions to deploy the add-on.

Manual installation of Ransomware Prevention

To install Ransomware Prevention, you will need to open a Command Prompt as an Administrator to run the installation files. There is no GUI for this installation. If you have any questions, create a support ticket for your Cybersecurity Advisor.

Task 1: Download Ransomware Prevention

You will need to download files for the Ransomware Prevention add-on specific to the operating system you are using. To get the required files, create a support ticket for your Cybersecurity Advisor.

Task 2: Install Ransomware Prevention

Insight Agent version

Ransomware Prevention for Windows operating systems require an Insight Agent version of 4.0.0.0 or higher. For more information, read the Ransomware Prevention requirements.

  1. Obtain the installation files from Task 1 with the latest version of Ransomware Prevention:
  • agentInstaller-x86_64.msi
  • MVArmorInstallation.msi

Do not rename the installation files

Renaming the installation files will cause issues with remote uninstallation.

  1. Install the Insight Agent

Already installed the Insight Agent?

If you are installing Ransomware Prevention on an existing Insight Agent, you can skip this step.

Decide which installation option to use

Decide which installation option to use

There are two main Agent Installation options available that can be used interchangeably:

What is a Token?

A token is your organization’s unique identifier that links the installed Insight Agents to your organization. When installing using the token, the Insight Agent reaches out to the Insight Platform to download the certificate files necessary for successful installation. This installation option requires connectivity to the Insight Platform directly through a Rapid7 Endpoint or a Collector.

If you are installing the agent in an environment with stricter network requirements, we recommend using the Certificate Package.

Your token consists of two parts:

  • The region identifier - This portion identifies the region where your organization is located. For example, us is the region identifier for the United States, while ca is the region identifier for Canada.

  • The Universally Unique Identifier (UUID) - The UUID represents the token itself. The API request initiated by the installer sends this UUID to the Insight Platform in order to retrieve the JSON document that contains all the necessary dependencies noted previously.

A fully generated token appears in the following format:

<region_id>:XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX

Note that the process of installation with a token, the Insight Agent installer will download the following dependencies onto your asset. All together, these dependencies are no more than 20KB in size:

  • client.key
  • client.crt
  • config.json
  • cafile.pem

If you intend to install the Insight Agent using your organization’s token:

  • Your assets must be able to communicate with the Insight Platform in order for the installer to download its necessary dependencies.
  • If your assets are deployed in a network with strict URL filtering rules in place, you may need to allowlist the following token resource endpoint to ensure that the installer can pull its configuration files from the Insight Platform. Substitute <REGION> with the code that applies to your data region: https://<REGION>.deployment.endpoint.ingress.rapid7.com/api/v1/get_agent_files
    • To determine your region, view the Insight Platform home for one of the following regions:
RegionDescription
usUnited States - 1
us2United States - 2
us3United States - 3
euEurope
caCanada
auAustralia
apJapan

What is the Certificate Package?

Certificate installation terminology

Note that the certificate installation was previously referred to under Advanced within the Insight Agent installation options.

The Certificate Package contains your unique organization's configuration files, which are required for successful installation of the agent. These files are downloaded seamlessly when installing with a token, but are provided here for easy access in case some of the assets in your environment don't have direct connectivity the Insight Platform through a Rapid7 Endpoint or a Collector. We recommend installing the Insight Agent using the Certificate Package in environments with stricter network requirements.

Your Certificate Package ZIP file contains the following security files in addition to the installer executable:

  • client.key
  • client.crt
  • config.json
  • cafile.pem

Expired Certificates

If you use the certificate package installation option to install the Insight Agent, your certificates will expire after 5 years. Insight Agents that were previously installed with a valid certificate are not impacted and will continue to update their SSL certificates. New installations of the Insight Agent using an expired certificate will not be able to fully connect to the Insight Platform to run jobs in InsightVM, InsightIDR, or InsightOps.

Refresh your Certificates

If you host your certificate package on a network share, or if it is baked into a golden image for a virtual machine, redownload your certificate package within 5 years to ensure new installations of the Insight Agent run correctly.

Install the Insight Agent using a Token

Install using a Token

Depending on your preferred method of installation, follow the instructions below.

Install using the Wizard

The installation wizard guides you through the setup process and automatically downloads the configuration files to the default directories.

Custom locations for configuration files

If you want to store the configuration files in a custom location, you’ll need to install the Insight Agent using the command line.

To install the Insight Agent using the wizard:

  1. Run the .msi installer.
  2. Follow the prompts to install the Insight Agent.
  3. When the Agent Pairing screen appears, select the Pair using a Token option.
  4. Enter your token in the provided field.
  5. Go through the remaining screens to complete the installation process. The Insight Agent will be installed as a service and appear with the name Rapid7 Insight Agent in your service manager.

What if I wasn’t prompted to enter my token?

If the Agent Pairing screen does not appear during the wizard, the installer may have detected existing dependencies for the Insight Agent on your asset. To resolve this issue, delete any of those files manually and try running the installer again.

Install using the command line

Running the Windows installer from the command line allows you to specify a custom path for the Insight Agent’s dependencies, configure any Insight Agent attributes for InsightVM, and perform a silent installation.

The following example command utilizes these flags:

  • CUSTOMCONFIGPATH - The absolute path where the installer downloads its dependencies. If you specify this path as a network share, the installer must have write access in order to place the files. Additionally, any local folder specified here must be a writable location that already exists.
  • CUSTOMTOKEN - The token you generated and copied from the Insight Agent download panel. Note that the token flag is always required. If the token is not specified, the installer will have no way to download the necessary dependencies.

Token `CUSTOMCONFIGPATH` functionality

Unlike its usage with the Certificate Package installer, the CUSTOMCONFIGPATH flag has a different function when used with the Token installer. In this example, the path you specify establishes the target directory where the installer will download and place its necessary configuration files.

If you omit this flag from your command line operation, all configuration files will download to the current directory of the installer.

To perform a silent installation of a token installer with a custom path, run the following command in a comment prompt.

 
1
msiexec /i agentInstaller-<installerType>.msi /l*v insight_agent_install_log.log CUSTOMCONFIGPATH=<target-directory-for-dependencies> CUSTOMTOKEN=<regionalID:UUID> /quiet

In the command, specify this information where indicated:

  • <installerType> - Specify x86_64 for most Windows architectures, or arm64 for Windows ARM64.
  • <target-directory-for-dependencies> - Specify your custom path.
  • <regionalID:UUID> - Specify your custom token.

The Insight Agent will be installed as a service and appear with the name Rapid7 Insight Agent in your service manager.

Install the Insight Agent using a Certificate Package

Install using a Certificate Package

Certificate Package SSL errors

Due to additional support added for the Insight Agent, deploying with Insight Agent certificate packages from before October 2023 can lead to SSL errors. Ensure all deployments use certificate packages downloaded after this date to safeguard our systems. You can download the latest certificate package from insight.rapid7.com > Data Collection Management > Agent Installer.

To successfully install the Insight Agent, ensure that the certificate and configuration files are in the same directory as the installer before you start the installation process. This also applies when reinstalling the Insight Agent using the installation wizard and the certificate package installer.

To install the Insight Agent using the Certificate Package on Windows assets:

  1. Fully extract the contents of your Certificate Package ZIP file. Make sure that the .msi installer and its dependencies are in the same directory.
  2. Run the .msi installer as an Administrator. The Insight Agent will be installed as a service and appear with the name Rapid7 Insight Agent in your service manager.

Silent installation on Windows

Administrator privileges required

You must run the Command Prompt with administrator privileges in order to perform a silent installation.

If you want to perform a silent installation of the Insight Agent, you can do so by running one of the following commands on the command line according to your system architecture:

For 32-bit installers and systems: msiexec /i agentInstaller-x86.msi /quiet

For 64-bit installers and systems: msiexec /i agentInstaller-x86_64.msi /quiet

For ARM64 installers and systems: msiexec /i agentInstaller-arm64.msi /quiet

  1. Open a Command Prompt as an Administrator and navigate to the extracted folder, which contains the MVArmorInstallation.msi file.

  2. Run the following command:

 
1
msiexec /i MVArmorInstallation.msi /qn /L*V ArmorInstallation.log

You can specify an existing Prevention Group for an asset to be included right after installation by including the DESIRED_GROUP=<groupname> parameter in the command.

Installation services and folders

Ransomware Prevention is installed as a service on your assets named Rapid7 Endpoint Prevention. Ransomware Prevention runs as two services on a 64-bit OS.

The Ransomware Prevention installation folder is located in C:\Program Files\Rapid7\Insight Agent\components\armor. Refer to the Endpoint Prevention overview for more information on how Ransomware Prevention works.

Verify Ransomware Prevention is deployed

Go to Command Platform > Administration > Data Collection > Agents to view the Endpoint Prevention tab. To verify if Ransomware Prevention has been deployed successfully, you must check if assets added to either the DEFAULT Prevention Group or a custom Prevention Group are visible here.

Update Ransomware Prevention

If you have enabled managed agent updates, you don't need to perform any manual tasks to update Ransomware Prevention. If you need to manually update the service, follow these instructions:

  1. Obtain the latest version of Ransomware Prevention, ensuring the file is in a directory that you can easily access with a Command Prompt.
  • MVArmorInstallation.msi
  1. Open a Command Prompt as an Administrator and navigate to the extracted folder, which contains the MVArmorInstallation.msi file.

If password protection is turned on, you will need to either get the one-time passcode or know the fixed password, if one is configured. The fixed password might be the organization-wide fixed password or one that is specific to the Prevention Group that the asset belongs to.

  1. Run one of these commands:
  • If password protection is turned on: msiexec /i MVArmorInstallation.msi /qn /L*V ArmorInstallation.log stop_service=<passcode or password>
  • If password protection is turned off: msiexec /i MVArmorInstallation.msi /qn /L*V ArmorInstallation.log

Stop and restart Ransomware Prevention

If you need to troubleshoot a problem, you can stop Ransomware Prevention on an asset, even if the asset's offline or has been disconnected.

If password protection is turned on, you will need to either get the one-time passcode or know the fixed password, if one is configured. The fixed password might be the organization-wide fixed password or one that is specific to the Prevention Group that the asset belongs to.

To stop Ransomware Prevention:

  1. Log into the asset on which you want to stop the Ransomware Prevention add-on.

  2. Open a Command Prompt as an Administrator and run one of these commands:

    • If password protection is turned on: C:\Program files\Rapid7\Insight Agent\components\armor\common\armor\MVarmorService32.exe --stop_service=<passcode or password>
    • If password protection is turned off: C:\Program files\Rapid7\Insight Agent\components\armor\common\armor\MVarmorService32.exe --stop_service

Note: The service can take several minutes to stop.

To restart Ransomware Prevention:

  1. In your Start menu, select Run > services.msc.
  2. Start the Rapid7 Endpoint Prevention 64bit service.

Uninstall Ransomware Prevention while leaving the agent intact

If password protection is turned on, you will need to either get the one-time passcode or know the fixed password, if one is configured. The fixed password might be the organization-wide fixed password or one that is specific to the Prevention Group that the asset belongs to.

  1. Open a Command Prompt as an Administrator and navigate to the directory where your Ransomware Prevention add-on is located.

  2. Run one of these commands:

    • If password protection is turned on: msiexec /x MVArmorInstallation.msi /qn stop_service=<passcode or password>
    • If password protection is turned off: msiexec /x MVArmorInstallation.msi /qn

If you want to generate a log file when the uninstallation finishes, you can run a modified edition of this command for that purpose. Substitute the {log-path} portion with the path where you want the log file to be placed:

 
1
msiexec /x MVArmorInstallation.msi /qn /L*V {log-path}

Uninstall an existing Insight Agent entirely

If you want to uninstall the Insight Agent entirely, note that you'll need to uninstall the Ransomware Prevention add-on first, then uninstall the rest of the Insight Agent. The Insight Agent will not allow itself to be uninstalled if any Endpoint Prevention add-on is still present.

You can uninstall the Insight Agent using the Add or remove programs tool in Windows:

  1. In your Start menu, select Control Panel.
  2. Under Programs, click Uninstall a program.
  3. Browse to Rapid7 Insight Agent and select it, then click Uninstall.

Next Steps

Once you have successfully installed the Ransomware Prevention add-on, view the configuration instructions to customise the add-on for your organization's needs.