macOS - Software Lifecycle - Install Rapid7 Insight Agent

What the Rapid7 Insight Agent deployment does

This Automox Worklet™ deploys the Rapid7 Insight Agent to macOS endpoints and registers each one with your Rapid7 Insight Platform tenant. The Worklet reads a Rapid7 user token from a secret input, detects the endpoint's processor architecture with uname -p, pulls the matching agent_control installer from us.storage.endpoint.ingress.rapid7.com, and runs the installer's install_start command with the token to complete certificate enrollment.

After install_start succeeds, the Rapid7 agent persists as a LaunchDaemon under the rapid7 label and the ir_agent binary lands at /opt/rapid7/ir_agent/ir_agent. The Worklet then confirms enrollment by re-checking launchctl list for the rapid7 service entry and verifying the ir_agent binary on disk before exiting 0.

The script is intentionally conservative on already-managed hosts. If launchctl shows the rapid7 service is running, the Worklet exits cleanly with no reinstall. If /opt/rapid7/ir_agent exists but the service is not loaded, the Worklet declines to reinstall so a broken state is surfaced rather than overwritten.

Why deploy the Rapid7 Insight Agent through Automox

A Mac without the Insight Agent is missing from your vulnerability program. InsightVM and InsightIDR both depend on the agent being installed, enrolled with a valid user token, and actively reporting through the Rapid7 ingress endpoint. The certificate-backed identity is established only when install_start runs with the token. Hosts that were manually installed without the token, or that lost their LaunchDaemon during an OS upgrade, do not appear in the Rapid7 console even though the binary may still be on disk.

Apply this Worklet to the macOS device group that should be reporting to Rapid7. The agent_installer runs from the Automox agent under root, the script detects Intel or Apple Silicon, the install_start step registers the endpoint with the token, and per-endpoint success or failure reports back through the Activity Log without an admin console session.

How Rapid7 Insight Agent deployment works

1. Evaluation phase: The Worklet runs launchctl list and greps for the rapid7 service label. A match means the agent is loaded and enrolled, and the endpoint exits 0 with no remediation. If the label is missing but /opt/rapid7/ir_agent exists on disk, the Worklet treats the host as broken-but-installed and exits 0 to avoid double-enrollment, surfacing the state in stdout. If neither condition is met, the endpoint is flagged non-compliant with exit 1 and remediation is scheduled.

2. Remediation phase: The script first verifies that the rapid7_token secret is bound to the policy and exits 1 with a stderr message if it is not. It then calls uname -p to branch the installer download: arm pulls agent_control_<build>_arm64.sh from the darwin/arm64 path of the Rapid7 ingress, anything else pulls the darwin/x86_64 build and saves it as agent_installer-x86_64.sh. The installer is chmod +x'd and invoked as ./agent_installer-<arch>.sh install_start --token "$rapid7_token", which performs certificate enrollment, lays down /opt/rapid7/ir_agent/ir_agent, and registers the rapid7 LaunchDaemon. The Worklet re-runs launchctl list to confirm the service loaded and checks that /opt/rapid7/ir_agent/ir_agent exists before exiting 0; any other state exits 1.

Rapid7 Insight Agent deployment requirements

• macOS endpoint on Intel x86_64 or Apple Silicon arm64 hardware, running a Rapid7-supported macOS release

• Active Rapid7 Insight Platform subscription with Insight Agent licensing (InsightVM or InsightIDR)

• A valid Rapid7 user token from the Rapid7 console, attached to the policy as a secret input named rapid7_token

• Root privileges for the Automox agent (default); required to write to /opt/rapid7/ and to register the rapid7 LaunchDaemon

• Outbound network access from each endpoint to us.storage.endpoint.ingress.rapid7.com over HTTPS for both installer download and ongoing agent telemetry

• No conflicting prior install at /opt/rapid7/ir_agent; remove a broken legacy install with the Uninstall Rapid7 Insight Agent Worklet before scheduling this one

Expected state after Rapid7 deployment

Each remediated endpoint reports the rapid7 LaunchDaemon as loaded under launchctl list and the ir_agent binary present at /opt/rapid7/ir_agent/ir_agent. The agent opens a persistent TLS session to the Rapid7 ingress endpoint and begins reporting asset inventory, installed software, and authenticated vulnerability findings to your Rapid7 Insight Platform tenant.

Validate on a pilot host by running launchctl list | grep rapid7 and confirming a numeric PID rather than a dash in the first column. Run ls -l /opt/rapid7/ir_agent/ir_agent to confirm the binary is present and executable. In the Rapid7 console, open Insight Platform → Data Collection Management → Insight Agent and confirm the new asset appears with a recent last-checkin timestamp. The Worklet exits 0 on the next evaluation pass without applying remediation again, because the launchctl check short-circuits the install path.