Mac Installation

This article guides you through the installation process for the 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 Insight Agent is allowed to run when detected.

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

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

Install the Insight Agent on macOS (.pkg)

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

Step 1: Install the 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 Insight Agent using .pkg package manager (ensure you substitute the {version} and {architecture} placeholder values before executing these commands):

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

Step 2: Configure the Insight Agent (.pkg)

With a Mac installation of the Insight Agent, you must configure the 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 Insight Agent for Mac operating systems, you must run the configure_agent.sh configuration script to connect the Insight Agent to the Insight Platform.

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

 
1
/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 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:

 
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

Configure the 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 Insight Agent service:

 
1
 sudo -i
2

3
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:

   
  1
  
  

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

 
1

Configure the 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 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 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 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 Insight Agent service:

 
1
./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 Insight Agent on macOS 15 or higher, you must give the Insight Agent Full Disk Access (FDA).

Use an MDM for configuration

To configure the Insight Agent with MDM software, download the 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 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 Insight Agent.

To verify Process Start Events are being generated locally:

To verify Process Start Events are being sent to InsightIDR:

Other useful commands (.pkg)

View the followings section for additional commands for your Insight Agent.

Verify the PKG signature

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

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

Manually start the Insight Agent service (.pkg)

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

 
1
launchctl start com.rapid7.ir_agent

Uninstall .pkg installer Insight Agents (.pkg)

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

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

 
1
launchctl list com.rapid7.ir_agent

Stop the Insight Agent service (.pkg)

 
1
launchctl stop com.rapid7.ir_agent

Check which Rapid7 Insight Agents are installed (.pkg)

 
1
pkgutil --pkgs | grep rapid7

Advanced installation options

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