Mac Installation

This article guides you through the installation process for the Rapid7 Agent (Insight Agent) on your assets if you are using the Mac Operating System.

Still need to download the installer? See the Download and Installation overview page for instructions on how to download the correct installer for the operating system of your intended asset.

Requirements

Before proceeding with the installation, verify that your intended asset is running a supported operating system and meets the connectivity requirements. If your organization also uses endpoint protection software, ensure that the Rapid7 Agent (Insight Agent) is allowed to run when detected.

If you are installing the Rapid7 Agent (Insight Agent) on macOS 15 or higher, there is an additional required configuration step you must complete.

The Rapid7 Agent (Insight Agent) installer supports proxy definitions. If you need to direct your Rapid7 Agents (Insight Agents) to send data through a proxy before reaching the Command Platform (Insight Platform), see the Proxy Configuration page for instructions

Install the Rapid7 Agent (Insight Agent) on macOS (.pkg)

The .pkg installer supports both the Token installation option and the Certificate Package installation option.

Step 1: Install the Rapid7 Agent (Insight Agent) (.pkg)

1. After downloading the .pkg file for the architecture of your choice, open a terminal and navigate to the directory where your download is located.
2. Run the following commands to install the Rapid7 Agent (Insight Agent) using .pkg package manager (ensure you substitute the {version} and {architecture} placeholder values before executing these commands):

installer -verbose -pkg rapid7-insight-agent-{version}-1.{architecture}.pkg -target /

Step 2: Configure the Rapid7 Agent (Insight Agent) (.pkg)

With a Mac installation of the Rapid7 Agent (Insight Agent), you must configure the Rapid7 Agent (Insight Agent) by using either the Token installation option or the Certificate Package installation option. Read more about these options in the overview page.

After installing the Rapid7 Agent (Insight Agent) for Mac operating systems, you must run the configure_agent.sh configuration script to connect the Rapid7 Agent (Insight Agent) to the Command Platform (Insight Platform).

You can find this script in the following location of your Rapid7 Agent (Insight Agent) installation directory ({version} will correspond to the Rapid7 Agent (Insight Agent) version you have just installed):

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

The configuration script also supports several arguments you can specify to configure a variety of Rapid7 Agent (Insight Agent) options. Run configure_agent.sh help in your terminal to display an explanation of these arguments. These details are reproduced here for your convenience:

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

-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

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

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

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

-s, --start: Start the Rapid7 Agent (Insight Agent) service after configuration is complete

-v: Prints all logs to stderr

--no_connectivity_check: Continue configuring the Rapid7 Agent (Insight Agent) when any connectivity checks fail

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

Configure the Rapid7 Agent (Insight Agent) using a Token (.pkg)

Note for this configuration option you will need to locate (or generate, if necessary) your organization’s token by navigating to insight.rapid7.com  > Data Collection > Agents > Agent Installer > Token Management.

Use the following configuration command, substituting {token} with your orgnization’s token and {proxy-address} with the IP address and port of your proxy. This example command also configures several attributes and starts the Rapid7 Agent (Insight Agent) service:

sudo -i

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

Run one of the following based on whether you have proxy and attributes:

• Without proxy and attributes:

  ./configure_agent.sh --token={token} -v --start

• With proxy and attributes:

  ./configure_agent.sh --token={token} -v --https-proxy={proxy-address} --attributes="attribute1,attribute2,attribute3,attribute4" --start

Configure the Rapid7 Agent (Insight Agent) using the Certificate Package (.pkg)

Note for this configuration option you will need to locate (or generate, if necessary) your organization’s token by navigating to insight.rapid7.com  > Data Collection > Agents > Agent Installer > Install the Rapid7 Agent (Insight Agent) using the Certificate Package > Download Certificate..

1. Extract the contents of the ZIP file to retrieve the following files:

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

When configuring the installation of the Rapid7 Agent (Insight Agent) for Mac, do not use the additional scripts that are included alongside these files, as they are not used in this procedure.

2. Relocate these certificate files to the installation directory of your installer Rapid7 Agent (Insight Agent).
3. Run the configuration script:
   • This example configuration script command targets the configuration files you just downloaded (substitute the {path-to-cert-files} with the local path where the files are stored), specifies a proxy address (substitute the {proxy-address} portion with the IP address and port of your proxy), and configures several attributes. Finally, the script is instructed to start the Rapid7 Agent (Insight Agent) service:

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

Additional configuration required for macOS 15 or higher

If you are installing an Rapid7 Agent (Insight Agent) on macOS 15 or higher, you must give the Rapid7 Agent (Insight Agent) Full Disk Access (FDA).

Use an MDM for configuration

To configure the Rapid7 Agent (Insight Agent) with MDM software, download the Rapid7 Agent (Insight Agent) FDA.mobileconfig  file. Depending on the MDM you are using, the following configuration may be required:

• Identifier: /opt/rapid7/ir_agent/ir_agent
  • Note: if you have downloaded the installer to another file location, ensure you enter the correct path to the ir_agent.
• Identifier type: path
• Code requirement: identifier bootstrap and anchor apple generic and certificate 1[field.1.2.840.113635.100.6.2.6] /* exists */ and certificate leaf[field.1.2.840.113635.100.6.1.13] /* exists */ and certificate leaf[subject.OU] = UL6CGN7MAL

Alternative option for configuration

Although it is recommended to use an MDM software for this step, if you cannot use an MDM software, you can manually grant Full Disk Access (FDA) to complete this configuration step.

To manually grant FDA:

Note: If you are using this method for configuration, you will also need to restart your Rapid7 Agent (Insight Agent) after following these instructions.

1. Open System Settings > Privacy & Security > Full Disk Access.

2. ir_agent will be visible on this list as long as Agent 4.0.12.14 is installed, and the darwin.ui_realtime job has started. Note that it can take a while for the ir_agent to appear following the darwin.ui_realtime job being started.

   • In case that ir_agent is not visible, follow these steps to add it manually. Note: you will require administrator privileges to complete these steps:

   Add the ir_agent manually

   1. Click + in the Full Disk Access window.
   2. In the resulting Finder window, press Command + Shift + G to open the dialogue box.
   3. Enter /opt/rapid7.
   4. Select the ir_agent directory, then click on Show in Finder from the menu options.
   5. In the Finder window, select the ir_agent directory and click Get Info from the menu options.
   6. Expand Sharing & Permissions, click the lock icon in the bottom right corner to unlock editing, then click +.
   7. Select the current user then click Select.
   8. Grant the current user read permission for the directory.
   9. Go back to the initial Finder window. You can now open the ir_agent directory.
   10. Select the ir_agent executable file and click Open. An entry of ir_agent will be visible in the Full Disk Access window.

   If the ir_agent was added manually, it’s recommended to remove the read permission added in these steps.

3. Enable ir_agent and close the window.

If you are still seeing the EndpointSecurity requires Full Disk Access permission for /opt/rapid7/ir_agent/ir_agent error in the Agent Log after the above steps, reboot the system.

Verify FDA has been enabled

Complete the following steps to check if FDA has been enabled for your Rapid7 Agent (Insight Agent).

To verify Process Start Events are being generated locally:

To verify Process Start Events are being sent to SIEM (InsightIDR):

Other useful commands (.pkg)

View the followings section for additional commands for your Rapid7 Agent (Insight Agent).

Verify the PKG signature

If you want to verify the PKG signature, you can do so with the following command:

pkgutil --check-signature rapid7-insight-agent-{version}-1.{architecture}.pkg

Manually start the Rapid7 Agent (Insight Agent) service (.pkg)

The configuration script detailed in step 2 features its own attribute that you can include to start the Rapid7 Agent (Insight Agent) service automatically. If you need to start the Rapid7 Agent (Insight Agent) service separately for any reason, you can do so with the following command:

launchctl start com.rapid7.ir_agent

Uninstall .pkg installer Rapid7 Agents (Insight Agents) (.pkg)

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

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

Check the status of the Rapid7 Agent (Insight Agent) service (.pkg)

launchctl list com.rapid7.ir_agent

Stop the Rapid7 Agent (Insight Agent) service (.pkg)

launchctl stop com.rapid7.ir_agent

Check which Rapid7 Agents (Insight Agents) are installed (.pkg)

pkgutil --pkgs | grep rapid7

Advanced installation options

The Rapid7 Agent (Insight Agent) has multiple advanced options for customization. Read more about these in our advanced installation options overview.