Install Next-Generation Antivirus

Task 1: Download Next-Generation Antivirus

You will need to download files for the Next-Generation Antivirus add-on specific to the operating system you are using. To attain the required files, create a support ticket for your Customer Advisor.

Task 2: Decide which installation option to use

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

• Token
• Certificate

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.
  • As long as you verify the network connectivity requirements noted previously, this communication channel will be available for use.
• 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:

What is the Certificate Package?

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.

Task 3: Install the Insight Agent with Next-Generation Antivirus

Once you have determined which option you would like to use in task 2, you’re ready to install the Insight Agent with the Next-Generation Antivirus add-on.

Follow the instructions below for the operating system of your choice:

 
1
rapid7_endpoint_prevention_installer.bat CUSTOMTOKEN={token}

 
1
rapid7_endpoint_prevention_installer.bat

 
1
installer -verbose -pkg rapid7-insight-agent-{version}-1.{architecture}.pkg -target /
2
installer -verbose -pkg rapid7-armor-{version}-1.{architecture}.pkg -target /
3
installer -verbose -pkg rapid7-armor360-{version}-1.{architecture}.pkg -target /
4
launchctl bootout system /Library/LaunchDaemons/com.rapid7.ir_agent.plist

 
1
/opt/rapid7/ir_agent/components/insight_agent/{version}/configure_agent.sh

 
1
-a, --attributes=ATTRIBUTES: Custom attributes may be used to identify and group Insight Agents in ways that are meaningful to your organization. Use commas to specify multiple attributes.  Example: --attributes=\"lab_system, managed, commercial\"
2

3
-c, --certificate_package_installation=PACKAGE_PATH: Supply a path to the configuration files if already downloaded or where they should be downloaded if using a token
4

5
-t, --token=TOKEN: Supply a token generated by the server in place of the config files
6

7
-p, --https-proxy=PROXY: Supply an HTTPS proxy for the Insight Agent to use when communicating with the Insight Platform.  Example: --https-proxy=example.rapid7.com:3128, with credentials --https-proxy=<username>:<password>@example.rapid7.com:3128
8

9
--disable-updates:  Disable Platform managed updates for all Insight Agent sub-components (default: False)
10

11
-s, --start: Start the Insight Agent service after configuration is complete
12

13
-v: Prints all logs to stderr
14

15
--no_connectivity_check: Continue configuring the Insight Agent when any connectivity checks fail
16

17
--no_version_check: If a newer version of this script is found, proceed with configuration

 
1
 sudo -i
2

3
cd /opt/rapid7/ir_agent/components/insight_agent/{version}/

 
1
./configure_agent.sh --certificate_package_installation {path-to-cert-files} -v --https-proxy={proxy-address} --attributes "attribute1,attribute2,attribute3,attribute4" --start

 
1
/opt/rapid7/ir_agent/components/insight_agent/{version}/configure_agent.sh

 
1
-a, --attributes=ATTRIBUTES: Custom attributes may be used to identify and group Insight Agents in ways that are meaningful to your organization. Use commas to specify multiple attributes.  Example: --attributes=\"lab_system, managed, commercial\"
2
-c, --certificate_package_installation=PACKAGE_PATH: Supply a path to the configuration files if already downloaded or where they should be downloaded if using a token
3
-t, --token=TOKEN: Supply a token generated by the server in place of the config files
4
-p, --https-proxy=PROXY: Supply an HTTPS proxy for the Insight Agent to use when communicating with the Insight Platform.  Example: --https-proxy=example.rapid7.com:3128, with credentials --https-proxy=<username>:<password>@example.rapid7.com:3128
5
--disable-updates:  Disable Insight Platform managed updates for all Insight Agent sub-components (default: False)
6
-s, --start: Start the Insight Agent service after configuration is complete
7
-v: Prints all logs to stderr
8
--no_connectivity_check: Continue configuring the Insight Agent when any connectivity checks fail
9
--no_version_check: If a newer version of this script is found, proceed with configuration

 
1
 sudo -i
2

3
cd /opt/rapid7/ir_agent/components/insight_agent/{version}/

 
1
./configure_agent.sh --certificate_package_installation {path-to-cert-files} -v --https-proxy={proxy-address} --attributes "attribute1,attribute2,attribute3,attribute4" --start

For a Token installation:

rapid7_endpoint_prevention_installer.bat CUSTOMTOKEN={token} DESIRED_GROUP=MyGroupName

For a Certificate Package installation:

rapid7_endpoint_prevention_installer.bat DESIRED_GROUP=MyGroupName

For a token configuration:

./configure_agent.sh -t=us:{token} --desired-group=MyGroupName --start

For a certificate package configuration:

./configure_agent.sh --desired-group=MyGroupName --start

For a token configuration:

./configure_agent.sh -t=us:{token} --desired-group=MyGroupName --start

For a certificate package configuration:

./configure_agent.sh --desired-group=MyGroupName --start

If you need to manually update Next-Generation Antivirus for Windows, you must include either the one-time passcode or fixed password as the final parameter of the command you run, in case password protection is on. Follow the instructions below, updating the service using either the Token or Certificate Package instructions based on which one you installed the Next-Generation Antivirus add-on with in task 2.

If you have enabled managed agent updates, you don't need to perform any manual tasks to update Next-Generation Antivirus.

To manually update the service:

1. In the Mac Terminal, run the following commands, substituting {version} and {architecture}:

 
1
installer -verbose -pkg rapid7-armor-{version}-1.{architecture}.pkg -target /
2
installer -verbose -pkg rapid7-armor360-{version}-1.{architecture}.pkg -target /
3
launchctl bootout system /Library/LaunchDaemons/com.rapid7.ir_agent.plist
4
launchctl load -w /Library/LaunchDaemons/com.rapid7.armor.plist

If you have enabled managed agent updates, you don't need to perform any manual tasks to update Next-Generation Antivirus.

To manually update the service:

1. Obtain the latest version of Next-Generation Antivirus, ensuring the files are in a directory that you can easily access with a command prompt.
2. Open a command prompt as an Administrator and navigate to the folder, which contains the install files.
3. Use the system’s package manager to update Armor, for example:
   • For RPM: sudo rpm -U rapid7-armor-linux-{version}_{architecture}.rpm
   • For DEB: sudo apt install ./rapid7-armor-linux_{version}_{architecture}.deb
4. Use the system’s package manager to update Armor360, for example:
   • For RPM: sudo rpm -U rapid7-armor360-linux-{version}_{architecture}.rpm
   • For DEB: sudo apt install ./rapid7-armor360-linux_{version}_{architecture}.deb
5. Run the following command to restart the Insight Agent: systemctl restart ir_agent

With password protection 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 Next-Generation Antivirus (Windows):

1. Log into the asset on which you want to stop the Next-Generation Antivirus add-on.
2. Open a command prompt as an Administrator and run this command, replacing <passcode or password> with either the one-time passcode you obtained from the Security Settings page or a fixed password that you configured:

C:\Program files\rapid7\Insight Agent\components\armor\common\armor\MVarmorService32.exe --stop_service <passcode or password>

Note: The service can take several minutes to stop.

To restart Next-Generation Antivirus (Windows):

1. In your Start menu, select Run > services.msc.
2. Depending on your asset, start either the Rapid7 Endpoint Prevention 64bit service or the Rapid7 Endpoint Prevention 32bit service.

To stop Next-Generation Antivirus (Mac):

launchctl bootout system /Library/LaunchDaemons/com.rapid7.armor.plist

To restart Next-Generation Antivirus (Mac):

launchctl bootstrap system /Library/LaunchDaemons/com.rapid7.armor.plist

To stop Next-Generation Antivirus (Linux):

sudo systemctl stop armor

To restart Next-Generation Antivirus (Linux):

sudo systemctl restart armor

The procedure for uninstalling Next-Generation Antivirus for Windows can vary depending on the type of your machine and if password protection is turned on:

To uninstall Next-Generation Antivirus for Windows with password protection:

1. Create a support ticket for your Customer Advisor to acquire the rapid7_ngav_uninstaller.bat file.
   • This file does not need to be installed in the same directory as the installer file was previously downloaded to.
2. In the command prompt, navigate to the directory where your Next-Generation Antivirus installer is located.
3. Run the following command: rapid7_ngav_uninstaller.bat STOP_SERVICE_PASSWORD=<password>
4. Uninstall Armor:
   1. For 32-bit machines: msiexec /x MVArmorInstallation_x86.msi /qn stop_service=<password>
   2. For 64-bit machines: msiexec /x MVArmorInstallation_x64.msi /qn stop_service=<password>

To uninstall Next-Generation Antivirus for Windows without password protection:

1. Create a support ticket for your Customer Advisor to acquire the rapid7_ngav_uninstaller.bat file.
   • This file does not need to be installed in the same directory as the installer file was previously downloaded to.
2. In the command prompt, navigate to the directory where your Next-Generation Antivirus installer is located.
3. Run the following command: rapid7_ngav_uninstaller.bat
4. Uninstall Armor:
   1. For 32-bit machines: msiexec /x MVArmorInstallation_x86.msi /qn
   2. For 64-bit machines: msiexec /x MVArmorInstallation_x64.msi /qn

Uninstall Armor360:

/opt/rapid7/ir_agent/components/armor360_darwin/{version}/uninstall.sh

Uninstall Rapid7 Endpoint Prevention (Next-Generation Antivirus):

/Library/Rapid7EndpointPrevention/AVP/product/bin/UninstallTool

Uninstall Armor:

/opt/rapid7/ir_agent/components/armor_darwin/{version}/uninstall.sh

Depending on your architecture, run the following command:

DEB:dpkg -r rapid7-armor360 rapid7endpointprevention rapid7-armor

RPM:rpm -e rapid7-armor360 rapid7endpointprevention rapid7-armor

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.

If you need to uninstall a .pkg version of the Insight Agent, you can do so with these APT commands:

 
1
sudo /opt/rapid7/ir_agent/components/insight_agent/{version}/uninstall.sh

Depending on your architecture, use the following command: